Check in tree-dce enh to trunk
[official-gcc.git] / gcc / fortran / intrinsic.texi
blob571f10e893f2a5d404163272aa3a9425d5890b6d
1 @ignore
2 Copyright (C) 2005, 2006, 2007, 2008
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.   
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``GNU General Public License'' and ``Funding
11 Free Software'', the Front-Cover texts being (a) (see below), and with
12 the Back-Cover Texts being (b) (see below).  A copy of the license is
13 included in the gfdl(7) man page.
16 Some basic guidelines for editing this document:
18   (1) The intrinsic procedures are to be listed in alphabetical order.
19   (2) The generic name is to be used.
20   (3) The specific names are included in the function index and in a
21       table at the end of the node (See ABS entry).
22   (4) Try to maintain the same style for each entry.
25 @end ignore
27 @tex
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}
34 @end tex
37 @node Intrinsic Procedures
38 @chapter Intrinsic Procedures
39 @cindex intrinsic procedures
41 @menu
42 * Introduction:         Introduction to Intrinsics
43 * @code{ABORT}:         ABORT,     Abort the program     
44 * @code{ABS}:           ABS,       Absolute value     
45 * @code{ACCESS}:        ACCESS,    Checks file access modes
46 * @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
47 * @code{ACOS}:          ACOS,      Arccosine function
48 * @code{ACOSH}:         ACOSH,     Hyperbolic arccosine function
49 * @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
50 * @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
51 * @code{AIMAG}:         AIMAG,     Imaginary part of complex number
52 * @code{AINT}:          AINT,      Truncate to a whole number
53 * @code{ALARM}:         ALARM,     Set an alarm clock
54 * @code{ALL}:           ALL,       Determine if all values are true
55 * @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
56 * @code{AND}:           AND,       Bitwise logical AND
57 * @code{ANINT}:         ANINT,     Nearest whole number
58 * @code{ANY}:           ANY,       Determine if any values are true
59 * @code{ASIN}:          ASIN,      Arcsine function
60 * @code{ASINH}:         ASINH,     Hyperbolic arcsine function
61 * @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
62 * @code{ATAN}:          ATAN,      Arctangent function
63 * @code{ATAN2}:         ATAN2,     Arctangent function
64 * @code{ATANH}:         ATANH,     Hyperbolic arctangent function
65 * @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
66 * @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
67 * @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
68 * @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
69 * @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
70 * @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
71 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
72 * @code{BTEST}:         BTEST,     Bit test function
73 * @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
74 * @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
75 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
76 * @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
77 * @code{C_LOC}:         C_LOC,     Obtain the C address of an object
78 * @code{CEILING}:       CEILING,   Integer ceiling function
79 * @code{CHAR}:          CHAR,      Integer-to-character conversion function
80 * @code{CHDIR}:         CHDIR,     Change working directory
81 * @code{CHMOD}:         CHMOD,     Change access permissions of files
82 * @code{CMPLX}:         CMPLX,     Complex conversion function
83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
84 * @code{COMPLEX}:       COMPLEX,   Complex conversion function
85 * @code{CONJG}:         CONJG,     Complex conjugate function
86 * @code{COS}:           COS,       Cosine function
87 * @code{COSH}:          COSH,      Hyperbolic cosine function
88 * @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
89 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
90 * @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
91 * @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
93 * @code{DBLE}:          DBLE,      Double precision conversion function
94 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
95 * @code{DFLOAT}:        DFLOAT,    Double precision conversion function
96 * @code{DIGITS}:        DIGITS,    Significant digits function
97 * @code{DIM}:           DIM,       Positive difference
98 * @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
99 * @code{DPROD}:         DPROD,     Double product function
100 * @code{DREAL}:         DREAL,     Double real part function
101 * @code{DTIME}:         DTIME,     Execution time subroutine (or function)
102 * @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
103 * @code{EPSILON}:       EPSILON,   Epsilon function
104 * @code{ERF}:           ERF,       Error function
105 * @code{ERFC}:          ERFC,      Complementary error function
106 * @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
107 * @code{ETIME}:         ETIME,     Execution time subroutine (or function)
108 * @code{EXIT}:          EXIT,      Exit the program with status.
109 * @code{EXP}:           EXP,       Exponential function
110 * @code{EXPONENT}:      EXPONENT,  Exponent function
111 * @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
112 * @code{FGET}:          FGET,      Read a single character in stream mode from stdin
113 * @code{FGETC}:         FGETC,     Read a single character in stream mode
114 * @code{FLOAT}:         FLOAT,     Convert integer to default real
115 * @code{FLOOR}:         FLOOR,     Integer floor function
116 * @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
117 * @code{FNUM}:          FNUM,      File number function
118 * @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
119 * @code{FPUTC}:         FPUTC,     Write a single character in stream mode
120 * @code{FRACTION}:      FRACTION,  Fractional part of the model representation
121 * @code{FREE}:          FREE,      Memory de-allocation subroutine
122 * @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
123 * @code{FSTAT}:         FSTAT,     Get file status
124 * @code{FTELL}:         FTELL,     Current stream position
125 * @code{GAMMA}:         GAMMA,     Gamma function
126 * @code{GERROR}:        GERROR,    Get last system error message
127 * @code{GETARG}:        GETARG,    Get command line arguments
128 * @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
129 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
130 * @code{GETCWD}:        GETCWD,    Get current working directory
131 * @code{GETENV}:        GETENV,    Get an environmental variable
132 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
133 * @code{GETGID}:        GETGID,    Group ID function
134 * @code{GETLOG}:        GETLOG,    Get login name
135 * @code{GETPID}:        GETPID,    Process ID function
136 * @code{GETUID}:        GETUID,    User ID function
137 * @code{GMTIME}:        GMTIME,    Convert time to GMT info
138 * @code{HOSTNM}:        HOSTNM,    Get system host name
139 * @code{HUGE}:          HUGE,      Largest number of a kind
140 * @code{HYPOT}:         HYPOT,     Euclidian distance function
141 * @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
142 * @code{IAND}:          IAND,      Bitwise logical and
143 * @code{IARGC}:         IARGC,     Get the number of command line arguments
144 * @code{IBCLR}:         IBCLR,     Clear bit
145 * @code{IBITS}:         IBITS,     Bit extraction
146 * @code{IBSET}:         IBSET,     Set bit
147 * @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
148 * @code{IDATE}:         IDATE,     Current local time (day/month/year)
149 * @code{IEOR}:          IEOR,      Bitwise logical exclusive or
150 * @code{IERRNO}:        IERRNO,    Function to get the last system error number
151 * @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
152 * @code{INT}:           INT,       Convert to integer type
153 * @code{INT2}:          INT2,      Convert to 16-bit integer type
154 * @code{INT8}:          INT8,      Convert to 64-bit integer type
155 * @code{IOR}:           IOR,       Bitwise logical or
156 * @code{IRAND}:         IRAND,     Integer pseudo-random number
157 * @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
158 * @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
159 * @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
160 * @code{ISHFT}:         ISHFT,     Shift bits
161 * @code{ISHFTC}:        ISHFTC,    Shift bits circularly
162 * @code{ISNAN}:         ISNAN,     Tests for a NaN
163 * @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
164 * @code{KILL}:          KILL,      Send a signal to a process
165 * @code{KIND}:          KIND,      Kind of an entity
166 * @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
167 * @code{LEN}:           LEN,       Length of a character entity
168 * @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
169 * @code{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
170 * @code{LGE}:           LGE,       Lexical greater than or equal
171 * @code{LGT}:           LGT,       Lexical greater than
172 * @code{LINK}:          LINK,      Create a hard link
173 * @code{LLE}:           LLE,       Lexical less than or equal
174 * @code{LLT}:           LLT,       Lexical less than
175 * @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
176 * @code{LOC}:           LOC,       Returns the address of a variable
177 * @code{LOG}:           LOG,       Logarithm function
178 * @code{LOG10}:         LOG10,     Base 10 logarithm function 
179 * @code{LOGICAL}:       LOGICAL,   Convert to logical type
180 * @code{LONG}:          LONG,      Convert to integer type
181 * @code{LSHIFT}:        LSHIFT,    Left shift bits
182 * @code{LSTAT}:         LSTAT,     Get file status
183 * @code{LTIME}:         LTIME,     Convert time to local time info
184 * @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
185 * @code{MATMUL}:        MATMUL,    matrix multiplication
186 * @code{MAX}:           MAX,       Maximum value of an argument list
187 * @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
188 * @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
189 * @code{MAXVAL}:        MAXVAL,    Maximum value of an array
190 * @code{MCLOCK}:        MCLOCK,    Time function
191 * @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
192 * @code{MERGE}:         MERGE,     Merge arrays
193 * @code{MIN}:           MIN,       Minimum value of an argument list
194 * @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
195 * @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
196 * @code{MINVAL}:        MINVAL,    Minimum value of an array
197 * @code{MOD}:           MOD,       Remainder function
198 * @code{MODULO}:        MODULO,    Modulo function
199 * @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
200 * @code{MVBITS}:        MVBITS,    Move bits from one integer to another
201 * @code{NEAREST}:       NEAREST,   Nearest representable number
202 * @code{NEW_LINE}:      NEW_LINE,  New line character
203 * @code{NINT}:          NINT,      Nearest whole number
204 * @code{NOT}:           NOT,       Logical negation
205 * @code{NULL}:          NULL,      Function that returns an disassociated pointer
206 * @code{OR}:            OR,        Bitwise logical OR
207 * @code{PACK}:          PACK,      Pack an array into an array of rank one
208 * @code{PERROR}:        PERROR,    Print system error message
209 * @code{PRECISION}:     PRECISION, Decimal precision of a real kind
210 * @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
211 * @code{PRODUCT}:       PRODUCT,   Product of array elements
212 * @code{RADIX}:         RADIX,     Base of a data model
213 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
214 * @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
215 * @code{RAND}:          RAND,      Real pseudo-random number
216 * @code{RANGE}:         RANGE,     Decimal exponent range of a real kind
217 * @code{RAN}:           RAN,       Real pseudo-random number
218 * @code{REAL}:          REAL,      Convert to real type 
219 * @code{RENAME}:        RENAME,    Rename a file
220 * @code{REPEAT}:        REPEAT,    Repeated string concatenation
221 * @code{RESHAPE}:       RESHAPE,   Function to reshape an array
222 * @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
223 * @code{RSHIFT}:        RSHIFT,    Right shift bits
224 * @code{SCALE}:         SCALE,     Scale a real value
225 * @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
226 * @code{SECNDS}:        SECNDS,    Time function
227 * @code{SECOND}:        SECOND,    CPU time function
228 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
229 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
230 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
231 * @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
232 * @code{SHAPE}:         SHAPE,     Determine the shape of an array
233 * @code{SIGN}:          SIGN,      Sign copying function
234 * @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
235 * @code{SIN}:           SIN,       Sine function
236 * @code{SINH}:          SINH,      Hyperbolic sine function
237 * @code{SIZE}:          SIZE,      Function to determine the size of an array
238 * @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
239 * @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
240 * @code{SNGL}:          SNGL,      Convert double precision real to default real
241 * @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
242 * @code{SPREAD}:        SPREAD,    Add a dimension to an array 
243 * @code{SQRT}:          SQRT,      Square-root function
244 * @code{SRAND}:         SRAND,     Reinitialize the random number generator
245 * @code{STAT}:          STAT,      Get file status
246 * @code{SUM}:           SUM,       Sum of array elements
247 * @code{SYMLNK}:        SYMLNK,    Create a symbolic link
248 * @code{SYSTEM}:        SYSTEM,    Execute a shell command
249 * @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
250 * @code{TAN}:           TAN,       Tangent function
251 * @code{TANH}:          TANH,      Hyperbolic tangent function
252 * @code{TIME}:          TIME,      Time function
253 * @code{TIME8}:         TIME8,     Time function (64-bit)
254 * @code{TINY}:          TINY,      Smallest positive number of a real kind
255 * @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
256 * @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
257 * @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
258 * @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
259 * @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
260 * @code{UMASK}:         UMASK,     Set the file creation mask
261 * @code{UNLINK}:        UNLINK,    Remove a file from the file system
262 * @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
263 * @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
264 * @code{XOR}:           XOR,       Bitwise logical exclusive or
265 @end menu
267 @node Introduction to Intrinsics
268 @section Introduction to intrinsic procedures
270 The intrinsic procedures provided by GNU Fortran include all of the
271 intrinsic procedures required by the Fortran 95 standard, a set of
272 intrinsic procedures for backwards compatibility with G77, and a
273 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
274 standards.  Any conflict between a description here and a description in
275 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
276 2008 standard is unintentional, and the standard(s) should be considered
277 authoritative.
279 The enumeration of the @code{KIND} type parameter is processor defined in
280 the Fortran 95 standard.  GNU Fortran defines the default integer type and
281 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
282 respectively.  The standard mandates that both data types shall have
283 another kind, which have more precision.  On typical target architectures
284 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
285 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
286 In the description of generic intrinsic procedures, the kind type parameter
287 will be specified by @code{KIND=*}, and in the description of specific
288 names for an intrinsic procedure the kind type parameter will be explicitly
289 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
290 brevity the optional @code{KIND=} syntax will be omitted.
292 Many of the intrinsic procedures take one or more optional arguments.
293 This document follows the convention used in the Fortran 95 standard,
294 and denotes such arguments by square brackets.
296 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
297 which can be used to restrict the set of intrinsic procedures to a 
298 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
299 option, and so all intrinsic procedures described here are accepted.  There
300 is one caveat.  For a select group of intrinsic procedures, @command{g77}
301 implemented both a function and a subroutine.  Both classes 
302 have been implemented in @command{gfortran} for backwards compatibility
303 with @command{g77}.  It is noted here that these functions and subroutines
304 cannot be intermixed in a given subprogram.  In the descriptions that follow,
305 the applicable standard for each intrinsic procedure is noted.
309 @node ABORT
310 @section @code{ABORT} --- Abort the program
311 @fnindex ABORT
312 @cindex program termination, with core dump
313 @cindex terminate program, with core dump
314 @cindex core, dump
316 @table @asis
317 @item @emph{Description}:
318 @code{ABORT} causes immediate termination of the program.  On operating
319 systems that support a core dump, @code{ABORT} will produce a core dump,
320 which is suitable for debugging purposes.
322 @item @emph{Standard}:
323 GNU extension
325 @item @emph{Class}:
326 Subroutine
328 @item @emph{Syntax}:
329 @code{CALL ABORT}
331 @item @emph{Return value}:
332 Does not return.
334 @item @emph{Example}:
335 @smallexample
336 program test_abort
337   integer :: i = 1, j = 2
338   if (i /= j) call abort
339 end program test_abort
340 @end smallexample
342 @item @emph{See also}:
343 @ref{EXIT}, @ref{KILL}
345 @end table
349 @node ABS
350 @section @code{ABS} --- Absolute value
351 @fnindex ABS
352 @fnindex CABS
353 @fnindex DABS
354 @fnindex IABS
355 @fnindex ZABS
356 @fnindex CDABS
357 @cindex absolute value
359 @table @asis
360 @item @emph{Description}:
361 @code{ABS(X)} computes the absolute value of @code{X}.
363 @item @emph{Standard}:
364 Fortran 77 and later, has overloads that are GNU extensions
366 @item @emph{Class}:
367 Elemental function
369 @item @emph{Syntax}:
370 @code{RESULT = ABS(X)}
372 @item @emph{Arguments}:
373 @multitable @columnfractions .15 .70
374 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
375 @code{REAL(*)}, or @code{COMPLEX(*)}.
376 @end multitable
378 @item @emph{Return value}:
379 The return value is of the same type and
380 kind as the argument except the return value is @code{REAL(*)} for a
381 @code{COMPLEX(*)} argument.
383 @item @emph{Example}:
384 @smallexample
385 program test_abs
386   integer :: i = -1
387   real :: x = -1.e0
388   complex :: z = (-1.e0,0.e0)
389   i = abs(i)
390   x = abs(x)
391   x = abs(z)
392 end program test_abs
393 @end smallexample
395 @item @emph{Specific names}:
396 @multitable @columnfractions .20 .20 .20 .25
397 @item Name            @tab Argument            @tab Return type       @tab Standard
398 @item @code{CABS(Z)}  @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)}    @tab Fortran 77 and later
399 @item @code{DABS(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}    @tab Fortran 77 and later
400 @item @code{IABS(I)}  @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
401 @item @code{ZABS(Z)}  @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
402 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
403 @end multitable
404 @end table
408 @node ACCESS
409 @section @code{ACCESS} --- Checks file access modes
410 @fnindex ACCESS
411 @cindex file system, access mode
413 @table @asis
414 @item @emph{Description}:
415 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 
416 exists, is readable, writable or executable. Except for the
417 executable check, @code{ACCESS} can be replaced by
418 Fortran 95's @code{INQUIRE}.
420 @item @emph{Standard}:
421 GNU extension
423 @item @emph{Class}:
424 Inquiry function
426 @item @emph{Syntax}:
427 @code{RESULT = ACCESS(NAME, MODE)}
429 @item @emph{Arguments}:
430 @multitable @columnfractions .15 .70
431 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
432 Tailing blank are ignored unless the character @code{achar(0)} is
433 present, then all characters up to and excluding @code{achar(0)} are
434 used as file name.
435 @item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,
436 may be any concatenation of @code{"r"} (readable), @code{"w"} (writable)
437 and @code{"x"} (executable), or @code{" "} to check for existence.
438 @end multitable
440 @item @emph{Return value}:
441 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
442 accessible in the given mode; otherwise or if an invalid argument
443 has been given for @code{MODE} the value @code{1} is returned.
445 @item @emph{Example}:
446 @smallexample
447 program access_test
448   implicit none
449   character(len=*), parameter :: file  = 'test.dat'
450   character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
451   if(access(file,' ') == 0) print *, trim(file),' is exists'
452   if(access(file,'r') == 0) print *, trim(file),' is readable'
453   if(access(file,'w') == 0) print *, trim(file),' is writable'
454   if(access(file,'x') == 0) print *, trim(file),' is executable'
455   if(access(file2,'rwx') == 0) &
456     print *, trim(file2),' is readable, writable and executable'
457 end program access_test
458 @end smallexample
459 @item @emph{Specific names}:
460 @item @emph{See also}:
462 @end table
466 @node ACHAR
467 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 
468 @fnindex ACHAR
469 @cindex @acronym{ASCII} collating sequence
470 @cindex collating sequence, @acronym{ASCII}
472 @table @asis
473 @item @emph{Description}:
474 @code{ACHAR(I)} returns the character located at position @code{I}
475 in the @acronym{ASCII} collating sequence.
477 @item @emph{Standard}:
478 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
480 @item @emph{Class}:
481 Elemental function
483 @item @emph{Syntax}:
484 @code{RESULT = ACHAR(I [, KIND])}
486 @item @emph{Arguments}:
487 @multitable @columnfractions .15 .70
488 @item @var{I}    @tab The type shall be @code{INTEGER(*)}.
489 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
490                       expression indicating the kind parameter of
491                       the result.
492 @end multitable
494 @item @emph{Return value}:
495 The return value is of type @code{CHARACTER} with a length of one.  The
496 kind type parameter is the same as  @code{KIND('A')}.
498 @item @emph{Example}:
499 @smallexample
500 program test_achar
501   character c
502   c = achar(32)
503 end program test_achar
504 @end smallexample
506 @item @emph{Note}:
507 See @ref{ICHAR} for a discussion of converting between numerical values
508 and formatted string representations.
510 @item @emph{See also}:
511 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
513 @end table
517 @node ACOS
518 @section @code{ACOS} --- Arccosine function 
519 @fnindex ACOS
520 @fnindex DACOS
521 @cindex trigonometric function, cosine, inverse
522 @cindex cosine, inverse
524 @table @asis
525 @item @emph{Description}:
526 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
528 @item @emph{Standard}:
529 Fortran 77 and later
531 @item @emph{Class}:
532 Elemental function
534 @item @emph{Syntax}:
535 @code{RESULT = ACOS(X)}
537 @item @emph{Arguments}:
538 @multitable @columnfractions .15 .70
539 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
540 less than one.
541 @end multitable
543 @item @emph{Return value}:
544 The return value is of type @code{REAL(*)} and it lies in the
545 range @math{ 0 \leq \acos(x) \leq \pi}. The kind type parameter 
546 is the same as @var{X}.
548 @item @emph{Example}:
549 @smallexample
550 program test_acos
551   real(8) :: x = 0.866_8
552   x = acos(x)
553 end program test_acos
554 @end smallexample
556 @item @emph{Specific names}:
557 @multitable @columnfractions .20 .20 .20 .25
558 @item Name            @tab Argument          @tab Return type       @tab Standard
559 @item @code{DACOS(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
560 @end multitable
562 @item @emph{See also}:
563 Inverse function: @ref{COS}
565 @end table
569 @node ACOSH
570 @section @code{ACOSH} --- Hyperbolic arccosine function
571 @fnindex ACOSH
572 @fnindex DACOSH
573 @cindex area hyperbolic cosine
574 @cindex hyperbolic arccosine
575 @cindex hyperbolic function, cosine, inverse
576 @cindex cosine, hyperbolic, inverse
578 @table @asis
579 @item @emph{Description}:
580 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
581 @code{COSH(X)}).
583 @item @emph{Standard}:
584 Fortran 2008 and later
586 @item @emph{Class}:
587 Elemental function
589 @item @emph{Syntax}:
590 @code{RESULT = ACOSH(X)}
592 @item @emph{Arguments}:
593 @multitable @columnfractions .15 .70
594 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
595 @end multitable
597 @item @emph{Return value}:
598 The return value has the same type and kind as @var{X}
600 @item @emph{Example}:
601 @smallexample
602 PROGRAM test_acosh
603   REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
604   WRITE (*,*) ACOSH(x)
605 END PROGRAM
606 @end smallexample
608 @item @emph{Specific names}:
609 @multitable @columnfractions .20 .20 .20 .25
610 @item Name             @tab Argument          @tab Return type       @tab Standard
611 @item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
612 @end multitable
614 @item @emph{See also}:
615 Inverse function: @ref{COSH}
616 @end table
620 @node ADJUSTL
621 @section @code{ADJUSTL} --- Left adjust a string 
622 @fnindex ADJUSTL
623 @cindex string, adjust left
624 @cindex adjust string
626 @table @asis
627 @item @emph{Description}:
628 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
629 Spaces are inserted at the end of the string as needed.
631 @item @emph{Standard}:
632 Fortran 95 and later
634 @item @emph{Class}:
635 Elemental function
637 @item @emph{Syntax}:
638 @code{RESULT = ADJUSTL(STR)}
640 @item @emph{Arguments}:
641 @multitable @columnfractions .15 .70
642 @item @var{STR} @tab The type shall be @code{CHARACTER}.
643 @end multitable
645 @item @emph{Return value}:
646 The return value is of type @code{CHARACTER} where leading spaces 
647 are removed and the same number of spaces are inserted on the end
648 of @var{STR}.
650 @item @emph{Example}:
651 @smallexample
652 program test_adjustl
653   character(len=20) :: str = '   gfortran'
654   str = adjustl(str)
655   print *, str
656 end program test_adjustl
657 @end smallexample
659 @item @emph{See also}:
660 @ref{ADJUSTR}, @ref{TRIM}
661 @end table
665 @node ADJUSTR
666 @section @code{ADJUSTR} --- Right adjust a string 
667 @fnindex ADJUSTR
668 @cindex string, adjust right
669 @cindex adjust string
671 @table @asis
672 @item @emph{Description}:
673 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
674 Spaces are inserted at the start of the string as needed.
676 @item @emph{Standard}:
677 Fortran 95 and later
679 @item @emph{Class}:
680 Elemental function
682 @item @emph{Syntax}:
683 @code{RESULT = ADJUSTR(STR)}
685 @item @emph{Arguments}:
686 @multitable @columnfractions .15 .70
687 @item @var{STR} @tab The type shall be @code{CHARACTER}.
688 @end multitable
690 @item @emph{Return value}:
691 The return value is of type @code{CHARACTER} where trailing spaces 
692 are removed and the same number of spaces are inserted at the start
693 of @var{STR}.
695 @item @emph{Example}:
696 @smallexample
697 program test_adjustr
698   character(len=20) :: str = 'gfortran'
699   str = adjustr(str)
700   print *, str
701 end program test_adjustr
702 @end smallexample
704 @item @emph{See also}:
705 @ref{ADJUSTL}, @ref{TRIM}
706 @end table
710 @node AIMAG
711 @section @code{AIMAG} --- Imaginary part of complex number  
712 @fnindex AIMAG
713 @fnindex DIMAG
714 @fnindex IMAG
715 @fnindex IMAGPART
716 @cindex complex numbers, imaginary part
718 @table @asis
719 @item @emph{Description}:
720 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
721 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
722 for compatibility with @command{g77}, and their use in new code is 
723 strongly discouraged.
725 @item @emph{Standard}:
726 Fortran 77 and later, has overloads that are GNU extensions
728 @item @emph{Class}:
729 Elemental function
731 @item @emph{Syntax}:
732 @code{RESULT = AIMAG(Z)}
734 @item @emph{Arguments}:
735 @multitable @columnfractions .15 .70
736 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
737 @end multitable
739 @item @emph{Return value}:
740 The return value is of type real with the
741 kind type parameter of the argument.
743 @item @emph{Example}:
744 @smallexample
745 program test_aimag
746   complex(4) z4
747   complex(8) z8
748   z4 = cmplx(1.e0_4, 0.e0_4)
749   z8 = cmplx(0.e0_8, 1.e0_8)
750   print *, aimag(z4), dimag(z8)
751 end program test_aimag
752 @end smallexample
754 @item @emph{Specific names}:
755 @multitable @columnfractions .20 .20 .20 .25
756 @item Name            @tab Argument            @tab Return type       @tab Standard
757 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}    @tab GNU extension
758 @item @code{IMAG(Z)}  @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)}    @tab GNU extension
759 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
760 @end multitable
761 @end table
765 @node AINT
766 @section @code{AINT} --- Truncate to a whole number
767 @fnindex AINT
768 @fnindex DINT
769 @cindex floor
770 @cindex rounding, floor
772 @table @asis
773 @item @emph{Description}:
774 @code{AINT(X [, KIND])} truncates its argument to a whole number.
776 @item @emph{Standard}:
777 Fortran 77 and later
779 @item @emph{Class}:
780 Elemental function
782 @item @emph{Syntax}:
783 @code{RESULT = AINT(X [, KIND])} 
785 @item @emph{Arguments}:
786 @multitable @columnfractions .15 .70
787 @item @var{X}    @tab The type of the argument shall be @code{REAL(*)}.
788 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
789                       expression indicating the kind parameter of
790                       the result.
791 @end multitable
793 @item @emph{Return value}:
794 The return value is of type real with the kind type parameter of the
795 argument if the optional @var{KIND} is absent; otherwise, the kind
796 type parameter will be given by @var{KIND}.  If the magnitude of 
797 @var{X} is less than one, then @code{AINT(X)} returns zero.  If the
798 magnitude is equal to or greater than one, then it returns the largest
799 whole number that does not exceed its magnitude.  The sign is the same
800 as the sign of @var{X}. 
802 @item @emph{Example}:
803 @smallexample
804 program test_aint
805   real(4) x4
806   real(8) x8
807   x4 = 1.234E0_4
808   x8 = 4.321_8
809   print *, aint(x4), dint(x8)
810   x8 = aint(x4,8)
811 end program test_aint
812 @end smallexample
814 @item @emph{Specific names}:
815 @multitable @columnfractions .20 .20 .20 .25
816 @item Name           @tab Argument         @tab Return type      @tab Standard
817 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab Fortran 77 and later
818 @end multitable
819 @end table
823 @node ALARM
824 @section @code{ALARM} --- Execute a routine after a given delay
825 @fnindex ALARM
826 @cindex delayed execution
828 @table @asis
829 @item @emph{Description}:
830 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
831 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
832 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
833 supplied, it will be returned with the number of seconds remaining until
834 any previously scheduled alarm was due to be delivered, or zero if there
835 was no previously scheduled alarm.
837 @item @emph{Standard}:
838 GNU extension
840 @item @emph{Class}:
841 Subroutine
843 @item @emph{Syntax}:
844 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
846 @item @emph{Arguments}:
847 @multitable @columnfractions .15 .70
848 @item @var{SECONDS} @tab The type of the argument shall be a scalar
849 @code{INTEGER}. It is @code{INTENT(IN)}.
850 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
851 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 
852 values may be either @code{SIG_IGN=1} to ignore the alarm generated 
853 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
854 @item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
855 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
856 @end multitable
858 @item @emph{Example}:
859 @smallexample
860 program test_alarm
861   external handler_print
862   integer i
863   call alarm (3, handler_print, i)
864   print *, i
865   call sleep(10)
866 end program test_alarm
867 @end smallexample
868 This will cause the external routine @var{handler_print} to be called
869 after 3 seconds.
870 @end table
874 @node ALL
875 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 
876 @fnindex ALL
877 @cindex array, apply condition
878 @cindex array, condition testing
880 @table @asis
881 @item @emph{Description}:
882 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
883 in the array along dimension @var{DIM}.
885 @item @emph{Standard}:
886 Fortran 95 and later
888 @item @emph{Class}:
889 Transformational function
891 @item @emph{Syntax}:
892 @code{RESULT = ALL(MASK [, DIM])}
894 @item @emph{Arguments}:
895 @multitable @columnfractions .15 .70
896 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
897 it shall not be scalar.
898 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
899 with a value that lies between one and the rank of @var{MASK}.
900 @end multitable
902 @item @emph{Return value}:
903 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
904 the kind type parameter is the same as the kind type parameter of
905 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
906 an array with the rank of @var{MASK} minus 1.  The shape is determined from
907 the shape of @var{MASK} where the @var{DIM} dimension is elided. 
909 @table @asis
910 @item (A)
911 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
912 It also is true if @var{MASK} has zero size; otherwise, it is false.
913 @item (B)
914 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
915 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
916 is determined by applying @code{ALL} to the array sections.
917 @end table
919 @item @emph{Example}:
920 @smallexample
921 program test_all
922   logical l
923   l = all((/.true., .true., .true./))
924   print *, l
925   call section
926   contains
927     subroutine section
928       integer a(2,3), b(2,3)
929       a = 1
930       b = 1
931       b(2,2) = 2
932       print *, all(a .eq. b, 1)
933       print *, all(a .eq. b, 2)
934     end subroutine section
935 end program test_all
936 @end smallexample
937 @end table
941 @node ALLOCATED
942 @section @code{ALLOCATED} --- Status of an allocatable entity
943 @fnindex ALLOCATED
944 @cindex allocation, status
946 @table @asis
947 @item @emph{Description}:
948 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
950 @item @emph{Standard}:
951 Fortran 95 and later
953 @item @emph{Class}:
954 Inquiry function
956 @item @emph{Syntax}:
957 @code{RESULT = ALLOCATED(X)}
959 @item @emph{Arguments}:
960 @multitable @columnfractions .15 .70
961 @item @var{X}    @tab The argument shall be an @code{ALLOCATABLE} array.
962 @end multitable
964 @item @emph{Return value}:
965 The return value is a scalar @code{LOGICAL} with the default logical
966 kind type parameter.  If @var{X} is allocated, @code{ALLOCATED(X)}
967 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.} 
969 @item @emph{Example}:
970 @smallexample
971 program test_allocated
972   integer :: i = 4
973   real(4), allocatable :: x(:)
974   if (allocated(x) .eqv. .false.) allocate(x(i))
975 end program test_allocated
976 @end smallexample
977 @end table
981 @node AND
982 @section @code{AND} --- Bitwise logical AND
983 @fnindex AND
984 @cindex bitwise logical and
985 @cindex logical and, bitwise
987 @table @asis
988 @item @emph{Description}:
989 Bitwise logical @code{AND}.
991 This intrinsic routine is provided for backwards compatibility with 
992 GNU Fortran 77.  For integer arguments, programmers should consider
993 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
995 @item @emph{Standard}:
996 GNU extension
998 @item @emph{Class}:
999 Function
1001 @item @emph{Syntax}:
1002 @code{RESULT = AND(I, J)}
1004 @item @emph{Arguments}:
1005 @multitable @columnfractions .15 .70
1006 @item @var{I} @tab The type shall be either a scalar @code{INTEGER(*)}
1007 type or a scalar @code{LOGICAL} type.
1008 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1009 @end multitable
1011 @item @emph{Return value}:
1012 The return type is either a scalar @code{INTEGER(*)} or a scalar
1013 @code{LOGICAL}.  If the kind type parameters differ, then the
1014 smaller kind type is implicitly converted to larger kind, and the 
1015 return has the larger kind.
1017 @item @emph{Example}:
1018 @smallexample
1019 PROGRAM test_and
1020   LOGICAL :: T = .TRUE., F = .FALSE.
1021   INTEGER :: a, b
1022   DATA a / Z'F' /, b / Z'3' /
1024   WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1025   WRITE (*,*) AND(a, b)
1026 END PROGRAM
1027 @end smallexample
1029 @item @emph{See also}:
1030 Fortran 95 elemental function: @ref{IAND}
1031 @end table
1035 @node ANINT
1036 @section @code{ANINT} --- Nearest whole number
1037 @fnindex ANINT
1038 @fnindex DNINT
1039 @cindex ceiling
1040 @cindex rounding, ceiling
1042 @table @asis
1043 @item @emph{Description}:
1044 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
1046 @item @emph{Standard}:
1047 Fortran 77 and later
1049 @item @emph{Class}:
1050 Elemental function
1052 @item @emph{Syntax}:
1053 @code{RESULT = ANINT(X [, KIND])}
1055 @item @emph{Arguments}:
1056 @multitable @columnfractions .15 .70
1057 @item @var{X}    @tab The type of the argument shall be @code{REAL(*)}.
1058 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1059                       expression indicating the kind parameter of
1060                       the result.
1061 @end multitable
1063 @item @emph{Return value}:
1064 The return value is of type real with the kind type parameter of the
1065 argument if the optional @var{KIND} is absent; otherwise, the kind
1066 type parameter will be given by @var{KIND}.  If @var{X} is greater than
1067 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}.  If @var{X} is
1068 less than or equal to zero, then it returns @code{AINT(X-0.5)}.
1070 @item @emph{Example}:
1071 @smallexample
1072 program test_anint
1073   real(4) x4
1074   real(8) x8
1075   x4 = 1.234E0_4
1076   x8 = 4.321_8
1077   print *, anint(x4), dnint(x8)
1078   x8 = anint(x4,8)
1079 end program test_anint
1080 @end smallexample
1082 @item @emph{Specific names}:
1083 @multitable @columnfractions .20 .20 .20 .25
1084 @item Name            @tab Argument         @tab Return type      @tab Standard
1085 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab Fortran 77 and later
1086 @end multitable
1087 @end table
1091 @node ANY
1092 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 
1093 @fnindex ANY
1094 @cindex array, apply condition
1095 @cindex array, condition testing
1097 @table @asis
1098 @item @emph{Description}:
1099 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1100 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1102 @item @emph{Standard}:
1103 Fortran 95 and later
1105 @item @emph{Class}:
1106 Transformational function
1108 @item @emph{Syntax}:
1109 @code{RESULT = ANY(MASK [, DIM])}
1111 @item @emph{Arguments}:
1112 @multitable @columnfractions .15 .70
1113 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
1114 it shall not be scalar.
1115 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1116 with a value that lies between one and the rank of @var{MASK}.
1117 @end multitable
1119 @item @emph{Return value}:
1120 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
1121 the kind type parameter is the same as the kind type parameter of
1122 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1123 an array with the rank of @var{MASK} minus 1.  The shape is determined from
1124 the shape of @var{MASK} where the @var{DIM} dimension is elided. 
1126 @table @asis
1127 @item (A)
1128 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1129 otherwise, it is false.  It also is false if @var{MASK} has zero size.
1130 @item (B)
1131 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1132 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1133 is determined by applying @code{ANY} to the array sections.
1134 @end table
1136 @item @emph{Example}:
1137 @smallexample
1138 program test_any
1139   logical l
1140   l = any((/.true., .true., .true./))
1141   print *, l
1142   call section
1143   contains
1144     subroutine section
1145       integer a(2,3), b(2,3)
1146       a = 1
1147       b = 1
1148       b(2,2) = 2
1149       print *, any(a .eq. b, 1)
1150       print *, any(a .eq. b, 2)
1151     end subroutine section
1152 end program test_any
1153 @end smallexample
1154 @end table
1158 @node ASIN
1159 @section @code{ASIN} --- Arcsine function 
1160 @fnindex ASIN
1161 @fnindex DASIN
1162 @cindex trigonometric function, sine, inverse
1163 @cindex sine, inverse
1165 @table @asis
1166 @item @emph{Description}:
1167 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1169 @item @emph{Standard}:
1170 Fortran 77 and later
1172 @item @emph{Class}:
1173 Elemental function
1175 @item @emph{Syntax}:
1176 @code{RESULT = ASIN(X)}
1178 @item @emph{Arguments}:
1179 @multitable @columnfractions .15 .70
1180 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
1181 less than one.
1182 @end multitable
1184 @item @emph{Return value}:
1185 The return value is of type @code{REAL(*)} and it lies in the
1186 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}.  The kind type
1187 parameter is the same as @var{X}.
1189 @item @emph{Example}:
1190 @smallexample
1191 program test_asin
1192   real(8) :: x = 0.866_8
1193   x = asin(x)
1194 end program test_asin
1195 @end smallexample
1197 @item @emph{Specific names}:
1198 @multitable @columnfractions .20 .20 .20 .25
1199 @item Name            @tab Argument          @tab Return type       @tab Standard
1200 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1201 @end multitable
1203 @item @emph{See also}:
1204 Inverse function: @ref{SIN}
1206 @end table
1210 @node ASINH
1211 @section @code{ASINH} --- Hyperbolic arcsine function
1212 @fnindex ASINH
1213 @fnindex DASINH
1214 @cindex area hyperbolic sine
1215 @cindex hyperbolic arcsine
1216 @cindex hyperbolic function, sine, inverse
1217 @cindex sine, hyperbolic, inverse
1219 @table @asis
1220 @item @emph{Description}:
1221 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1223 @item @emph{Standard}:
1224 Fortran 2008 and later
1226 @item @emph{Class}:
1227 Elemental function
1229 @item @emph{Syntax}:
1230 @code{RESULT = ASINH(X)}
1232 @item @emph{Arguments}:
1233 @multitable @columnfractions .15 .70
1234 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1235 @end multitable
1237 @item @emph{Return value}:
1238 The return value is of the same type and kind as  @var{X}.
1240 @item @emph{Example}:
1241 @smallexample
1242 PROGRAM test_asinh
1243   REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1244   WRITE (*,*) ASINH(x)
1245 END PROGRAM
1246 @end smallexample
1248 @item @emph{Specific names}:
1249 @multitable @columnfractions .20 .20 .20 .25
1250 @item Name             @tab Argument          @tab Return type       @tab Standard
1251 @item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1252 @end multitable
1254 @item @emph{See also}:
1255 Inverse function: @ref{SINH}
1256 @end table
1260 @node ASSOCIATED
1261 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 
1262 @fnindex ASSOCIATED
1263 @cindex pointer, status
1264 @cindex association status
1266 @table @asis
1267 @item @emph{Description}:
1268 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
1269 or if @var{PTR} is associated with the target @var{TGT}.
1271 @item @emph{Standard}:
1272 Fortran 95 and later
1274 @item @emph{Class}:
1275 Inquiry function
1277 @item @emph{Syntax}:
1278 @code{RESULT = ASSOCIATED(PTR [, TGT])}
1280 @item @emph{Arguments}:
1281 @multitable @columnfractions .15 .70
1282 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
1283 it can be of any type.
1284 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
1285 a @code{TARGET}.  It must have the same type, kind type parameter, and
1286 array rank as @var{PTR}.
1287 @end multitable
1288 The status of neither @var{PTR} nor @var{TGT} can be undefined.
1290 @item @emph{Return value}:
1291 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
1292 There are several cases:
1293 @table @asis
1294 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
1295 is true if @var{PTR} is associated with a target; otherwise, it returns false.
1296 @item (B) If @var{TGT} is present and a scalar target, the result is true if
1297 @var{TGT}
1298 is not a 0 sized storage sequence and the target associated with @var{PTR}
1299 occupies the same storage units.  If @var{PTR} is disassociated, then the 
1300 result is false.
1301 @item (C) If @var{TGT} is present and an array target, the result is true if
1302 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
1303 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
1304 @var{PTR} occupy the same storage units in array element order.
1305 As in case(B), the result is false, if @var{PTR} is disassociated.
1306 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
1307 target associated with @var{PTR} and the target associated with @var{TGT}
1308 are not 0 sized storage sequences and occupy the same storage units.
1309 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1310 @item (E) If @var{TGT} is present and an array pointer, the result is true if
1311 target associated with @var{PTR} and the target associated with @var{TGT}
1312 have the same shape, are not 0 sized arrays, are arrays whose elements are
1313 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
1314 storage units in array element order.
1315 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1316 @end table
1318 @item @emph{Example}:
1319 @smallexample
1320 program test_associated
1321    implicit none
1322    real, target  :: tgt(2) = (/1., 2./)
1323    real, pointer :: ptr(:)
1324    ptr => tgt
1325    if (associated(ptr)     .eqv. .false.) call abort
1326    if (associated(ptr,tgt) .eqv. .false.) call abort
1327 end program test_associated
1328 @end smallexample
1330 @item @emph{See also}:
1331 @ref{NULL}
1332 @end table
1336 @node ATAN
1337 @section @code{ATAN} --- Arctangent function 
1338 @fnindex ATAN
1339 @fnindex DATAN
1340 @cindex trigonometric function, tangent, inverse
1341 @cindex tangent, inverse
1343 @table @asis
1344 @item @emph{Description}:
1345 @code{ATAN(X)} computes the arctangent of @var{X}.
1347 @item @emph{Standard}:
1348 Fortran 77 and later
1350 @item @emph{Class}:
1351 Elemental function
1353 @item @emph{Syntax}:
1354 @code{RESULT = ATAN(X)}
1356 @item @emph{Arguments}:
1357 @multitable @columnfractions .15 .70
1358 @item @var{X} @tab The type shall be @code{REAL(*)}.
1359 @end multitable
1361 @item @emph{Return value}:
1362 The return value is of type @code{REAL(*)} and it lies in the
1363 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1365 @item @emph{Example}:
1366 @smallexample
1367 program test_atan
1368   real(8) :: x = 2.866_8
1369   x = atan(x)
1370 end program test_atan
1371 @end smallexample
1373 @item @emph{Specific names}:
1374 @multitable @columnfractions .20 .20 .20 .25
1375 @item Name            @tab Argument          @tab Return type       @tab Standard
1376 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1377 @end multitable
1379 @item @emph{See also}:
1380 Inverse function: @ref{TAN}
1382 @end table
1386 @node ATAN2
1387 @section @code{ATAN2} --- Arctangent function 
1388 @fnindex ATAN2
1389 @fnindex DATAN2
1390 @cindex trigonometric function, tangent, inverse
1391 @cindex tangent, inverse
1393 @table @asis
1394 @item @emph{Description}:
1395 @code{ATAN2(Y,X)} computes the arctangent of the complex number
1396 @math{X + i Y}.
1398 @item @emph{Standard}:
1399 Fortran 77 and later
1401 @item @emph{Class}:
1402 Elemental function
1404 @item @emph{Syntax}:
1405 @code{RESULT = ATAN2(Y,X)}
1407 @item @emph{Arguments}:
1408 @multitable @columnfractions .15 .70
1409 @item @var{Y} @tab The type shall be @code{REAL(*)}.
1410 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1411 If @var{Y} is zero, then @var{X} must be nonzero.
1412 @end multitable
1414 @item @emph{Return value}:
1415 The return value has the same type and kind type parameter as @var{Y}.
1416 It is the principal value of the complex number @math{X + i Y}.  If
1417 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1418 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1419 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1420 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
1421 is @math{\pi/2}.
1423 @item @emph{Example}:
1424 @smallexample
1425 program test_atan2
1426   real(4) :: x = 1.e0_4, y = 0.5e0_4
1427   x = atan2(y,x)
1428 end program test_atan2
1429 @end smallexample
1431 @item @emph{Specific names}:
1432 @multitable @columnfractions .20 .20 .20 .25
1433 @item Name            @tab Argument          @tab Return type    @tab Standard
1434 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1435 @end multitable
1436 @end table
1440 @node ATANH
1441 @section @code{ATANH} --- Hyperbolic arctangent function
1442 @fnindex ASINH
1443 @fnindex DASINH
1444 @cindex area hyperbolic tangent
1445 @cindex hyperbolic arctangent
1446 @cindex hyperbolic function, tangent, inverse
1447 @cindex tangent, hyperbolic, inverse
1449 @table @asis
1450 @item @emph{Description}:
1451 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1452 of @code{TANH(X)}).
1454 @item @emph{Standard}:
1455 Fortran 2008 and later
1457 @item @emph{Class}:
1458 Elemental function
1460 @item @emph{Syntax}:
1461 @code{RESULT = ATANH(X)}
1463 @item @emph{Arguments}:
1464 @multitable @columnfractions .15 .70
1465 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1466 @end multitable
1468 @item @emph{Return value}:
1469 The return value has same type and kind as @var{X}.
1471 @item @emph{Example}:
1472 @smallexample
1473 PROGRAM test_atanh
1474   REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1475   WRITE (*,*) ATANH(x)
1476 END PROGRAM
1477 @end smallexample
1479 @item @emph{Specific names}:
1480 @multitable @columnfractions .20 .20 .20 .25
1481 @item Name             @tab Argument          @tab Return type       @tab Standard
1482 @item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1483 @end multitable
1485 @item @emph{See also}:
1486 Inverse function: @ref{TANH}
1487 @end table
1491 @node BESSEL_J0
1492 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1493 @fnindex BESSEL_J0
1494 @fnindex BESJ0
1495 @fnindex DBESJ0
1496 @cindex Bessel function, first kind
1498 @table @asis
1499 @item @emph{Description}:
1500 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1501 order 0 of @var{X}. This function is available under the name
1502 @code{BESJ0} as a GNU extension.
1504 @item @emph{Standard}:
1505 Fortran 2008 and later
1507 @item @emph{Class}:
1508 Elemental function
1510 @item @emph{Syntax}:
1511 @code{RESULT = BESSEL_J0(X)}
1513 @item @emph{Arguments}:
1514 @multitable @columnfractions .15 .70
1515 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1516 @end multitable
1518 @item @emph{Return value}:
1519 The return value is of type @code{REAL(*)} and it lies in the
1520 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
1522 @item @emph{Example}:
1523 @smallexample
1524 program test_besj0
1525   real(8) :: x = 0.0_8
1526   x = bessel_j0(x)
1527 end program test_besj0
1528 @end smallexample
1530 @item @emph{Specific names}:
1531 @multitable @columnfractions .20 .20 .20 .25
1532 @item Name            @tab Argument          @tab Return type       @tab Standard
1533 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1534 @end multitable
1535 @end table
1539 @node BESSEL_J1
1540 @section @code{BESEL_J1} --- Bessel function of the first kind of order 1
1541 @fnindex BESSEL_J1
1542 @fnindex BESJ1
1543 @fnindex DBESJ1
1544 @cindex Bessel function, first kind
1546 @table @asis
1547 @item @emph{Description}:
1548 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1549 order 1 of @var{X}. This function is available under the name
1550 @code{BESJ1} as a GNU extension.
1552 @item @emph{Standard}:
1553 Fortran 2008
1555 @item @emph{Class}:
1556 Elemental function
1558 @item @emph{Syntax}:
1559 @code{RESULT = BESSEL_J1(X)}
1561 @item @emph{Arguments}:
1562 @multitable @columnfractions .15 .70
1563 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1564 @end multitable
1566 @item @emph{Return value}:
1567 The return value is of type @code{REAL(*)} and it lies in the
1568 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1570 @item @emph{Example}:
1571 @smallexample
1572 program test_besj1
1573   real(8) :: x = 1.0_8
1574   x = bessel_j1(x)
1575 end program test_besj1
1576 @end smallexample
1578 @item @emph{Specific names}:
1579 @multitable @columnfractions .20 .20 .20 .25
1580 @item Name            @tab Argument          @tab Return type       @tab Standard
1581 @item @code{DBESJ1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1582 @end multitable
1583 @end table
1587 @node BESSEL_JN
1588 @section @code{BESSEL_JN} --- Bessel function of the first kind
1589 @fnindex BESSEL_JN
1590 @fnindex BESJN
1591 @fnindex DBESJN
1592 @cindex Bessel function, first kind
1594 @table @asis
1595 @item @emph{Description}:
1596 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1597 order @var{N} of @var{X}. This function is available under the name
1598 @code{BESJN} as a GNU extension.
1600 If both arguments are arrays, their ranks and shapes shall conform.
1602 @item @emph{Standard}:
1603 Fortran 2008 and later
1605 @item @emph{Class}:
1606 Elemental function
1608 @item @emph{Syntax}:
1609 @code{RESULT = BESSEL_JN(N, X)}
1611 @item @emph{Arguments}:
1612 @multitable @columnfractions .15 .70
1613 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER(*)}.
1614 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL(*)}.
1615 @end multitable
1617 @item @emph{Return value}:
1618 The return value is a scalar of type @code{REAL(*)}.
1620 @item @emph{Example}:
1621 @smallexample
1622 program test_besjn
1623   real(8) :: x = 1.0_8
1624   x = bessel_jn(5,x)
1625 end program test_besjn
1626 @end smallexample
1628 @item @emph{Specific names}:
1629 @multitable @columnfractions .20 .20 .20 .25
1630 @item Name             @tab Argument            @tab Return type       @tab Standard
1631 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)}    @tab GNU extension
1632 @item                  @tab @code{REAL(8) X}    @tab                   @tab
1633 @end multitable
1634 @end table
1638 @node BESSEL_Y0
1639 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1640 @fnindex BESSEL_Y0
1641 @fnindex BESY0
1642 @fnindex DBESY0
1643 @cindex Bessel function, second kind
1645 @table @asis
1646 @item @emph{Description}:
1647 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1648 order 0 of @var{X}. This function is available under the name
1649 @code{BESY0} as a GNU extension.
1651 @item @emph{Standard}:
1652 Fortran 2008 and later
1654 @item @emph{Class}:
1655 Elemental function
1657 @item @emph{Syntax}:
1658 @code{RESULT = BESSEL_Y0(X)}
1660 @item @emph{Arguments}:
1661 @multitable @columnfractions .15 .70
1662 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1663 @end multitable
1665 @item @emph{Return value}:
1666 The return value is a scalar of type @code{REAL(*)}.
1668 @item @emph{Example}:
1669 @smallexample
1670 program test_besy0
1671   real(8) :: x = 0.0_8
1672   x = bessel_y0(x)
1673 end program test_besy0
1674 @end smallexample
1676 @item @emph{Specific names}:
1677 @multitable @columnfractions .20 .20 .20 .25
1678 @item Name            @tab Argument          @tab Return type       @tab Standard
1679 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1680 @end multitable
1681 @end table
1685 @node BESSEL_Y1
1686 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1687 @fnindex BESSEL_Y1
1688 @fnindex BESY1
1689 @fnindex DBESY1
1690 @cindex Bessel function, second kind
1692 @table @asis
1693 @item @emph{Description}:
1694 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1695 order 1 of @var{X}. This function is available under the name
1696 @code{BESY1} as a GNU extension.
1698 @item @emph{Standard}:
1699 Fortran 2008 and later
1701 @item @emph{Class}:
1702 Elemental function
1704 @item @emph{Syntax}:
1705 @code{RESULT = BESSEL_Y1(X)}
1707 @item @emph{Arguments}:
1708 @multitable @columnfractions .15 .70
1709 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1710 @end multitable
1712 @item @emph{Return value}:
1713 The return value is a scalar of type @code{REAL(*)}.
1715 @item @emph{Example}:
1716 @smallexample
1717 program test_besy1
1718   real(8) :: x = 1.0_8
1719   x = bessel_y1(x)
1720 end program test_besy1
1721 @end smallexample
1723 @item @emph{Specific names}:
1724 @multitable @columnfractions .20 .20 .20 .25
1725 @item Name            @tab Argument          @tab Return type       @tab Standard
1726 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1727 @end multitable
1728 @end table
1732 @node BESSEL_YN
1733 @section @code{BESSEL_YN} --- Bessel function of the second kind
1734 @fnindex BESSEL_YN
1735 @fnindex BESYN
1736 @fnindex DBESYN
1737 @cindex Bessel function, second kind
1739 @table @asis
1740 @item @emph{Description}:
1741 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1742 order @var{N} of @var{X}. This function is available under the name
1743 @code{BESYN} as a GNU extension.
1745 If both arguments are arrays, their ranks and shapes shall conform.
1747 @item @emph{Standard}:
1748 Fortran 2008 and later
1750 @item @emph{Class}:
1751 Elemental function
1753 @item @emph{Syntax}:
1754 @code{RESULT = BESSEL_YN(N, X)}
1756 @item @emph{Arguments}:
1757 @multitable @columnfractions .15 .70
1758 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER(*)}.
1759 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL(*)}.
1760 @end multitable
1762 @item @emph{Return value}:
1763 The return value is a scalar of type @code{REAL(*)}.
1765 @item @emph{Example}:
1766 @smallexample
1767 program test_besyn
1768   real(8) :: x = 1.0_8
1769   x = bessel_yn(5,x)
1770 end program test_besyn
1771 @end smallexample
1773 @item @emph{Specific names}:
1774 @multitable @columnfractions .20 .20 .20 .25
1775 @item Name               @tab Argument            @tab Return type     @tab Standard
1776 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)}  @tab GNU extension
1777 @item                    @tab @code{REAL(8)    X} @tab                 @tab 
1778 @end multitable
1779 @end table
1783 @node BIT_SIZE
1784 @section @code{BIT_SIZE} --- Bit size inquiry function
1785 @fnindex BIT_SIZE
1786 @cindex bits, number of
1787 @cindex size of a variable, in bits
1789 @table @asis
1790 @item @emph{Description}:
1791 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1792 represented by the type of @var{I}.
1794 @item @emph{Standard}:
1795 Fortran 95 and later
1797 @item @emph{Class}:
1798 Inquiry function
1800 @item @emph{Syntax}:
1801 @code{RESULT = BIT_SIZE(I)}
1803 @item @emph{Arguments}:
1804 @multitable @columnfractions .15 .70
1805 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1806 @end multitable
1808 @item @emph{Return value}:
1809 The return value is of type @code{INTEGER(*)}
1811 @item @emph{Example}:
1812 @smallexample
1813 program test_bit_size
1814     integer :: i = 123
1815     integer :: size
1816     size = bit_size(i)
1817     print *, size
1818 end program test_bit_size
1819 @end smallexample
1820 @end table
1824 @node BTEST
1825 @section @code{BTEST} --- Bit test function
1826 @fnindex BTEST
1827 @cindex bits, testing
1829 @table @asis
1830 @item @emph{Description}:
1831 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1832 in @var{I} is set.
1834 @item @emph{Standard}:
1835 Fortran 95 and later
1837 @item @emph{Class}:
1838 Elemental function
1840 @item @emph{Syntax}:
1841 @code{RESULT = BTEST(I, POS)}
1843 @item @emph{Arguments}:
1844 @multitable @columnfractions .15 .70
1845 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1846 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1847 @end multitable
1849 @item @emph{Return value}:
1850 The return value is of type @code{LOGICAL}
1852 @item @emph{Example}:
1853 @smallexample
1854 program test_btest
1855     integer :: i = 32768 + 1024 + 64
1856     integer :: pos
1857     logical :: bool
1858     do pos=0,16
1859         bool = btest(i, pos) 
1860         print *, pos, bool
1861     end do
1862 end program test_btest
1863 @end smallexample
1864 @end table
1867 @node C_ASSOCIATED
1868 @section @code{C_ASSOCIATED} --- Status of a C pointer
1869 @fnindex C_ASSOCIATED
1870 @cindex association status, C pointer
1871 @cindex pointer, C association status
1873 @table @asis
1874 @item @emph{Description}:
1875 @code{C_ASSOCIATED(c_prt1[, c_ptr2])} determines the status of the C pointer @var{c_ptr1}
1876 or if @var{c_ptr1} is associated with the target @var{c_ptr2}.
1878 @item @emph{Standard}:
1879 Fortran 2003 and later
1881 @item @emph{Class}:
1882 Inquiry function
1884 @item @emph{Syntax}:
1885 @code{RESULT = C_ASSOCIATED(c_prt1[, c_ptr2])}
1887 @item @emph{Arguments}:
1888 @multitable @columnfractions .15 .70
1889 @item @var{c_ptr1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1890 @item @var{c_ptr2} @tab (Optional) Scalar of the same type as @var{c_ptr1}.
1891 @end multitable
1893 @item @emph{Return value}:
1894 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1895 @var{c_ptr1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr2}
1896 point to different addresses.
1898 @item @emph{Example}:
1899 @smallexample
1900 subroutine association_test(a,b)
1901   use iso_c_binding, only: c_associated, c_loc, c_ptr
1902   implicit none
1903   real, pointer :: a
1904   type(c_ptr) :: b
1905   if(c_associated(b, c_loc(a))) &
1906      stop 'b and a do not point to same target'
1907 end subroutine association_test
1908 @end smallexample
1910 @item @emph{See also}:
1911 @ref{C_LOC}, @ref{C_FUNLOC}
1912 @end table
1915 @node C_FUNLOC
1916 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1917 @fnindex C_FUNLOC
1918 @cindex pointer, C address of procedures
1920 @table @asis
1921 @item @emph{Description}:
1922 @code{C_FUNLOC(x)} determines the C address of the argument.
1924 @item @emph{Standard}:
1925 Fortran 2003 and later
1927 @item @emph{Class}:
1928 Inquiry function
1930 @item @emph{Syntax}:
1931 @code{RESULT = C_FUNLOC(x)}
1933 @item @emph{Arguments}:
1934 @multitable @columnfractions .15 .70
1935 @item @var{x} @tab Interoperable function or pointer to such function.
1936 @end multitable
1938 @item @emph{Return value}:
1939 The return value is of type @code{C_FUNPTR} and contains the C address
1940 of the argument.
1942 @item @emph{Example}:
1943 @smallexample
1944 module x
1945   use iso_c_binding
1946   implicit none
1947 contains
1948   subroutine sub(a) bind(c)
1949     real(c_float) :: a
1950     a = sqrt(a)+5.0
1951   end subroutine sub
1952 end module x
1953 program main
1954   use iso_c_binding
1955   use x
1956   implicit none
1957   interface
1958     subroutine my_routine(p) bind(c,name='myC_func')
1959       import :: c_funptr
1960       type(c_funptr), intent(in) :: p
1961     end subroutine
1962   end interface
1963   call my_routine(c_funloc(sub))
1964 end program main
1965 @end smallexample
1967 @item @emph{See also}:
1968 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1969 @end table
1972 @node C_F_PROCPOINTER
1973 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1974 @fnindex C_F_PROCPOINTER
1975 @cindex pointer, C address of pointers
1977 @table @asis
1978 @item @emph{Description}:
1979 @code{C_F_PROCPOINTER(cptr, fptr)} Assign the target of the C function pointer
1980 @var{cptr} to the Fortran procedure pointer @var{fptr}.
1982 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1983 this function is not fully operable.
1985 @item @emph{Standard}:
1986 Fortran 2003 and later
1988 @item @emph{Class}:
1989 Subroutine
1991 @item @emph{Syntax}:
1992 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
1994 @item @emph{Arguments}:
1995 @multitable @columnfractions .15 .70
1996 @item @var{cptr}  @tab scalar of the type @code{C_FUNPTR}. It is
1997                        @code{INTENT(IN)}.
1998 @item @var{fptr}  @tab procedure pointer interoperable with @var{cptr}. It is
1999                        @code{INTENT(OUT)}.
2000 @end multitable
2002 @item @emph{Example}:
2003 @smallexample
2004 program main
2005   use iso_c_binding
2006   implicit none
2007   abstract interface
2008     function func(a)
2009       import :: c_float
2010       real(c_float), intent(in) :: a
2011       real(c_float) :: func
2012     end function
2013   end interface
2014   interface
2015      function getIterFunc() bind(c,name="getIterFunc")
2016        import :: c_funptr
2017        type(c_funptr) :: getIterFunc
2018      end function
2019   end interface
2020   type(c_funptr) :: cfunptr
2021   procedure(func), pointer :: myFunc
2022   cfunptr = getIterFunc()
2023   call c_f_procpointer(cfunptr, myFunc)
2024 end program main
2025 @end smallexample
2027 @item @emph{See also}:
2028 @ref{C_LOC}, @ref{C_F_POINTER}
2029 @end table
2032 @node C_F_POINTER
2033 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2034 @fnindex C_F_POINTER
2035 @cindex pointer, convert C to Fortran
2037 @table @asis
2038 @item @emph{Description}:
2039 @code{C_F_POINTER(cptr, fptr[, shape])} Assign the target the C pointer
2040 @var{cptr} to the Fortran pointer @var{fptr} and specify its
2041 shape.
2043 @item @emph{Standard}:
2044 Fortran 2003 and later
2046 @item @emph{Class}:
2047 Subroutine
2049 @item @emph{Syntax}:
2050 @code{CALL C_F_POINTER(cptr, fptr[, shape])}
2052 @item @emph{Arguments}:
2053 @multitable @columnfractions .15 .70
2054 @item @var{cptr}  @tab scalar of the type @code{C_PTR}. It is
2055                        @code{INTENT(IN)}.
2056 @item @var{fptr}  @tab pointer interoperable with @var{cptr}. It is
2057                        @code{INTENT(OUT)}.
2058 @item @var{shape} @tab (Optional) Rank-one array of type @code{INTEGER}
2059                        with @code{INTENT(IN)}. It shall be present
2060                        if and only if @var{fptr} is an array. The size
2061                        must be equal to the rank of @var{fptr}.
2062 @end multitable
2064 @item @emph{Example}:
2065 @smallexample
2066 program main
2067   use iso_c_binding
2068   implicit none
2069   interface
2070     subroutine my_routine(p) bind(c,name='myC_func')
2071       import :: c_ptr
2072       type(c_ptr), intent(out) :: p
2073     end subroutine
2074   end interface
2075   type(c_ptr) :: cptr
2076   real,pointer :: a(:)
2077   call my_routine(cptr)
2078   call c_f_pointer(cptr, a, [12])
2079 end program main
2080 @end smallexample
2082 @item @emph{See also}:
2083 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2084 @end table
2087 @node C_LOC
2088 @section @code{C_LOC} --- Obtain the C address of an object
2089 @fnindex C_LOC
2090 @cindex procedure pointer, convert C to Fortran
2092 @table @asis
2093 @item @emph{Description}:
2094 @code{C_LOC(x)} determines the C address of the argument.
2096 @item @emph{Standard}:
2097 Fortran 2003 and later
2099 @item @emph{Class}:
2100 Inquiry function
2102 @item @emph{Syntax}:
2103 @code{RESULT = C_LOC(x)}
2105 @item @emph{Arguments}:
2106 @multitable @columnfractions .15 .70
2107 @item @var{x} @tab Associated scalar pointer or interoperable scalar
2108                    or allocated allocatable variable with @code{TARGET}
2109                    attribute.
2110 @end multitable
2112 @item @emph{Return value}:
2113 The return value is of type @code{C_PTR} and contains the C address
2114 of the argument.
2116 @item @emph{Example}:
2117 @smallexample
2118 subroutine association_test(a,b)
2119   use iso_c_binding, only: c_associated, c_loc, c_ptr
2120   implicit none
2121   real, pointer :: a
2122   type(c_ptr) :: b
2123   if(c_associated(b, c_loc(a))) &
2124      stop 'b and a do not point to same target'
2125 end subroutine association_test
2126 @end smallexample
2128 @item @emph{See also}:
2129 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2130 @end table
2133 @node CEILING
2134 @section @code{CEILING} --- Integer ceiling function
2135 @fnindex CEILING
2136 @cindex ceiling
2137 @cindex rounding, ceiling
2139 @table @asis
2140 @item @emph{Description}:
2141 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
2143 @item @emph{Standard}:
2144 Fortran 95 and later
2146 @item @emph{Class}:
2147 Elemental function
2149 @item @emph{Syntax}:
2150 @code{RESULT = CEILING(X [, KIND])}
2152 @item @emph{Arguments}:
2153 @multitable @columnfractions .15 .70
2154 @item @var{X} @tab The type shall be @code{REAL(*)}.
2155 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2156                       expression indicating the kind parameter of
2157                       the result.
2158 @end multitable
2160 @item @emph{Return value}:
2161 The return value is of type @code{INTEGER(KIND)}
2163 @item @emph{Example}:
2164 @smallexample
2165 program test_ceiling
2166     real :: x = 63.29
2167     real :: y = -63.59
2168     print *, ceiling(x) ! returns 64
2169     print *, ceiling(y) ! returns -63
2170 end program test_ceiling
2171 @end smallexample
2173 @item @emph{See also}:
2174 @ref{FLOOR}, @ref{NINT}
2176 @end table
2180 @node CHAR
2181 @section @code{CHAR} --- Character conversion function
2182 @fnindex CHAR
2183 @cindex conversion, to character
2185 @table @asis
2186 @item @emph{Description}:
2187 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2189 @item @emph{Standard}:
2190 Fortran 77 and later
2192 @item @emph{Class}:
2193 Elemental function
2195 @item @emph{Syntax}:
2196 @code{RESULT = CHAR(I [, KIND])}
2198 @item @emph{Arguments}:
2199 @multitable @columnfractions .15 .70
2200 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
2201 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2202                       expression indicating the kind parameter of
2203                       the result.
2204 @end multitable
2206 @item @emph{Return value}:
2207 The return value is of type @code{CHARACTER(1)}
2209 @item @emph{Example}:
2210 @smallexample
2211 program test_char
2212     integer :: i = 74
2213     character(1) :: c
2214     c = char(i)
2215     print *, i, c ! returns 'J'
2216 end program test_char
2217 @end smallexample
2219 @item @emph{Note}:
2220 See @ref{ICHAR} for a discussion of converting between numerical values
2221 and formatted string representations.
2223 @item @emph{See also}:
2224 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2226 @end table
2230 @node CHDIR
2231 @section @code{CHDIR} --- Change working directory
2232 @fnindex CHDIR
2233 @cindex system, working directory
2235 @table @asis
2236 @item @emph{Description}:
2237 Change current working directory to a specified path.
2239 This intrinsic is provided in both subroutine and function forms; however,
2240 only one form can be used in any given program unit.
2242 @item @emph{Standard}:
2243 GNU extension
2245 @item @emph{Class}:
2246 Subroutine, function
2248 @item @emph{Syntax}:
2249 @multitable @columnfractions .80
2250 @item @code{CALL CHDIR(NAME [, STATUS])}
2251 @item @code{STATUS = CHDIR(NAME)}
2252 @end multitable
2254 @item @emph{Arguments}:
2255 @multitable @columnfractions .15 .70
2256 @item @var{NAME}   @tab The type shall be @code{CHARACTER(*)} and shall
2257                         specify a valid path within the file system.
2258 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2259                         kind.  Returns 0 on success, and a system specific
2260                         and nonzero error code otherwise.
2261 @end multitable
2263 @item @emph{Example}:
2264 @smallexample
2265 PROGRAM test_chdir
2266   CHARACTER(len=255) :: path
2267   CALL getcwd(path)
2268   WRITE(*,*) TRIM(path)
2269   CALL chdir("/tmp")
2270   CALL getcwd(path)
2271   WRITE(*,*) TRIM(path)
2272 END PROGRAM
2273 @end smallexample
2275 @item @emph{See also}:
2276 @ref{GETCWD}
2277 @end table
2281 @node CHMOD
2282 @section @code{CHMOD} --- Change access permissions of files
2283 @fnindex CHMOD
2284 @cindex file system, change access mode
2286 @table @asis
2287 @item @emph{Description}:
2288 @code{CHMOD} changes the permissions of a file. This function invokes
2289 @code{/bin/chmod} and might therefore not work on all platforms.
2291 This intrinsic is provided in both subroutine and function forms; however,
2292 only one form can be used in any given program unit.
2294 @item @emph{Standard}:
2295 GNU extension
2297 @item @emph{Class}:
2298 Subroutine, function
2300 @item @emph{Syntax}:
2301 @multitable @columnfractions .80
2302 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2303 @item @code{STATUS = CHMOD(NAME, MODE)}
2304 @end multitable
2306 @item @emph{Arguments}:
2307 @multitable @columnfractions .15 .70
2308 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
2309 Trailing blanks are ignored unless the character @code{achar(0)} is
2310 present, then all characters up to and excluding @code{achar(0)} are
2311 used as the file name.
2313 @item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
2314 @var{MODE} uses the same syntax as the @var{MODE} argument of
2315 @code{/bin/chmod}.
2317 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2318 @code{0} on success and nonzero otherwise.
2319 @end multitable
2321 @item @emph{Return value}:
2322 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2323 otherwise.
2325 @item @emph{Example}:
2326 @code{CHMOD} as subroutine
2327 @smallexample
2328 program chmod_test
2329   implicit none
2330   integer :: status
2331   call chmod('test.dat','u+x',status)
2332   print *, 'Status: ', status
2333 end program chmod_test
2334 @end smallexample
2335 @code{CHMOD} as function:
2336 @smallexample
2337 program chmod_test
2338   implicit none
2339   integer :: status
2340   status = chmod('test.dat','u+x')
2341   print *, 'Status: ', status
2342 end program chmod_test
2343 @end smallexample
2345 @end table
2349 @node CMPLX
2350 @section @code{CMPLX} --- Complex conversion function
2351 @fnindex CMPLX
2352 @cindex complex numbers, conversion to
2353 @cindex conversion, to complex
2355 @table @asis
2356 @item @emph{Description}:
2357 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2358 the real component.  If @var{Y} is present it is converted to the imaginary
2359 component.  If @var{Y} is not present then the imaginary component is set to
2360 0.0.  If @var{X} is complex then @var{Y} must not be present.
2362 @item @emph{Standard}:
2363 Fortran 77 and later
2365 @item @emph{Class}:
2366 Elemental function
2368 @item @emph{Syntax}:
2369 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2371 @item @emph{Arguments}:
2372 @multitable @columnfractions .15 .70
2373 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2374                    or @code{COMPLEX(*)}.
2375 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2376                    @code{COMPLEX(*)}.)  May be @code{INTEGER(*)}
2377                    or @code{REAL(*)}.
2378 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2379                       expression indicating the kind parameter of
2380                       the result.
2381 @end multitable
2383 @item @emph{Return value}:
2384 The return value is of @code{COMPLEX} type, with a kind equal to
2385 @var{KIND} if it is specified.  If @var{KIND} is not specified, the
2386 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2387 @var{X} and @var{Y}. 
2389 @item @emph{Example}:
2390 @smallexample
2391 program test_cmplx
2392     integer :: i = 42
2393     real :: x = 3.14
2394     complex :: z
2395     z = cmplx(i, x)
2396     print *, z, cmplx(x)
2397 end program test_cmplx
2398 @end smallexample
2400 @item @emph{See also}:
2401 @ref{COMPLEX}
2402 @end table
2406 @node COMMAND_ARGUMENT_COUNT
2407 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2408 @fnindex COMMAND_ARGUMENT_COUNT
2409 @cindex command-line arguments
2410 @cindex command-line arguments, number of
2411 @cindex arguments, to program
2413 @table @asis
2414 @item @emph{Description}:
2415 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2416 command line when the containing program was invoked.
2418 @item @emph{Standard}:
2419 Fortran 2003 and later
2421 @item @emph{Class}:
2422 Inquiry function
2424 @item @emph{Syntax}:
2425 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2427 @item @emph{Arguments}:
2428 @multitable @columnfractions .15 .70
2429 @item None
2430 @end multitable
2432 @item @emph{Return value}:
2433 The return value is of type @code{INTEGER(4)}
2435 @item @emph{Example}:
2436 @smallexample
2437 program test_command_argument_count
2438     integer :: count
2439     count = command_argument_count()
2440     print *, count
2441 end program test_command_argument_count
2442 @end smallexample
2444 @item @emph{See also}:
2445 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2446 @end table
2450 @node COMPLEX
2451 @section @code{COMPLEX} --- Complex conversion function
2452 @fnindex COMPLEX
2453 @cindex complex numbers, conversion to
2454 @cindex conversion, to complex
2456 @table @asis
2457 @item @emph{Description}:
2458 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2459 to the real component and @var{Y} is converted to the imaginary
2460 component.
2462 @item @emph{Standard}:
2463 GNU extension
2465 @item @emph{Class}:
2466 Elemental function
2468 @item @emph{Syntax}:
2469 @code{RESULT = COMPLEX(X, Y)}
2471 @item @emph{Arguments}:
2472 @multitable @columnfractions .15 .70
2473 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2474 @item @var{Y} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2475 @end multitable
2477 @item @emph{Return value}:
2478 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2479 value is of default @code{COMPLEX} type.
2481 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2482 type and one is of @code{INTEGER} type, then the return value is of
2483 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2484 argument with the highest precision.  
2486 @item @emph{Example}:
2487 @smallexample
2488 program test_complex
2489     integer :: i = 42
2490     real :: x = 3.14
2491     print *, complex(i, x)
2492 end program test_complex
2493 @end smallexample
2495 @item @emph{See also}:
2496 @ref{CMPLX}
2497 @end table
2501 @node CONJG
2502 @section @code{CONJG} --- Complex conjugate function 
2503 @fnindex CONJG
2504 @fnindex DCONJG
2505 @cindex complex conjugate
2507 @table @asis
2508 @item @emph{Description}:
2509 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2510 then the result is @code{(x, -y)}
2512 @item @emph{Standard}:
2513 Fortran 77 and later, has overloads that are GNU extensions
2515 @item @emph{Class}:
2516 Elemental function
2518 @item @emph{Syntax}:
2519 @code{Z = CONJG(Z)}
2521 @item @emph{Arguments}:
2522 @multitable @columnfractions .15 .70
2523 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
2524 @end multitable
2526 @item @emph{Return value}:
2527 The return value is of type @code{COMPLEX(*)}.
2529 @item @emph{Example}:
2530 @smallexample
2531 program test_conjg
2532     complex :: z = (2.0, 3.0)
2533     complex(8) :: dz = (2.71_8, -3.14_8)
2534     z= conjg(z)
2535     print *, z
2536     dz = dconjg(dz)
2537     print *, dz
2538 end program test_conjg
2539 @end smallexample
2541 @item @emph{Specific names}:
2542 @multitable @columnfractions .20 .20 .20 .25
2543 @item Name             @tab Argument             @tab Return type          @tab Standard
2544 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)}    @tab GNU extension
2545 @end multitable
2546 @end table
2550 @node COS
2551 @section @code{COS} --- Cosine function 
2552 @fnindex COS
2553 @fnindex DCOS
2554 @fnindex CCOS
2555 @fnindex ZCOS
2556 @fnindex CDCOS
2557 @cindex trigonometric function, cosine
2558 @cindex cosine
2560 @table @asis
2561 @item @emph{Description}:
2562 @code{COS(X)} computes the cosine of @var{X}.
2564 @item @emph{Standard}:
2565 Fortran 77 and later, has overloads that are GNU extensions
2567 @item @emph{Class}:
2568 Elemental function
2570 @item @emph{Syntax}:
2571 @code{RESULT = COS(X)}
2573 @item @emph{Arguments}:
2574 @multitable @columnfractions .15 .70
2575 @item @var{X} @tab The type shall be @code{REAL(*)} or
2576 @code{COMPLEX(*)}.
2577 @end multitable
2579 @item @emph{Return value}:
2580 The return value is of type @code{REAL(*)} and it lies in the
2581 range @math{ -1 \leq \cos (x) \leq 1}.  The kind type
2582 parameter is the same as @var{X}.
2584 @item @emph{Example}:
2585 @smallexample
2586 program test_cos
2587   real :: x = 0.0
2588   x = cos(x)
2589 end program test_cos
2590 @end smallexample
2592 @item @emph{Specific names}:
2593 @multitable @columnfractions .20 .20 .20 .25
2594 @item Name            @tab Argument            @tab Return type       @tab Standard
2595 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
2596 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2597 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2598 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2599 @end multitable
2601 @item @emph{See also}:
2602 Inverse function: @ref{ACOS}
2604 @end table
2608 @node COSH
2609 @section @code{COSH} --- Hyperbolic cosine function 
2610 @fnindex COSH
2611 @fnindex DCOSH
2612 @cindex hyperbolic cosine
2613 @cindex hyperbolic function, cosine
2614 @cindex cosine, hyperbolic
2616 @table @asis
2617 @item @emph{Description}:
2618 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2620 @item @emph{Standard}:
2621 Fortran 77 and later
2623 @item @emph{Class}:
2624 Elemental function
2626 @item @emph{Syntax}:
2627 @code{X = COSH(X)}
2629 @item @emph{Arguments}:
2630 @multitable @columnfractions .15 .70
2631 @item @var{X} @tab The type shall be @code{REAL(*)}.
2632 @end multitable
2634 @item @emph{Return value}:
2635 The return value is of type @code{REAL(*)} and it is positive
2636 (@math{ \cosh (x) \geq 0 }.
2638 @item @emph{Example}:
2639 @smallexample
2640 program test_cosh
2641   real(8) :: x = 1.0_8
2642   x = cosh(x)
2643 end program test_cosh
2644 @end smallexample
2646 @item @emph{Specific names}:
2647 @multitable @columnfractions .20 .20 .20 .25
2648 @item Name            @tab Argument          @tab Return type       @tab Standard
2649 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
2650 @end multitable
2652 @item @emph{See also}:
2653 Inverse function: @ref{ACOSH}
2655 @end table
2659 @node COUNT
2660 @section @code{COUNT} --- Count function
2661 @fnindex COUNT
2662 @cindex array, conditionally count elements
2663 @cindex array, element counting
2664 @cindex array, number of elements
2666 @table @asis
2667 @item @emph{Description}:
2669 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2670 elements of @var{MASK} along the dimension of @var{DIM}.  If @var{DIM} is
2671 omitted it is taken to be @code{1}.  @var{DIM} is a scaler of type
2672 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2673 is the rank of @var{MASK}.
2675 @item @emph{Standard}:
2676 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2678 @item @emph{Class}:
2679 Transformational function
2681 @item @emph{Syntax}:
2682 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2684 @item @emph{Arguments}:
2685 @multitable @columnfractions .15 .70
2686 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2687 @item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
2688 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2689                       expression indicating the kind parameter of
2690                       the result.
2691 @end multitable
2693 @item @emph{Return value}:
2694 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2695 @var{KIND} is absent, the return value is of default integer kind.
2696 The result has a rank equal to that of @var{MASK}.
2698 @item @emph{Example}:
2699 @smallexample
2700 program test_count
2701     integer, dimension(2,3) :: a, b
2702     logical, dimension(2,3) :: mask
2703     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2704     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2705     print '(3i3)', a(1,:)
2706     print '(3i3)', a(2,:)
2707     print *
2708     print '(3i3)', b(1,:)
2709     print '(3i3)', b(2,:)
2710     print *
2711     mask = a.ne.b
2712     print '(3l3)', mask(1,:)
2713     print '(3l3)', mask(2,:)
2714     print *
2715     print '(3i3)', count(mask)
2716     print *
2717     print '(3i3)', count(mask, 1)
2718     print *
2719     print '(3i3)', count(mask, 2)
2720 end program test_count
2721 @end smallexample
2722 @end table
2726 @node CPU_TIME
2727 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2728 @fnindex CPU_TIME
2729 @cindex time, elapsed
2731 @table @asis
2732 @item @emph{Description}:
2733 Returns a @code{REAL(*)} value representing the elapsed CPU time in
2734 seconds.  This is useful for testing segments of code to determine
2735 execution time.
2737 If a time source is available, time will be reported with microsecond
2738 resolution. If no time source is available, @var{TIME} is set to
2739 @code{-1.0}.
2741 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2742 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2743 value is meaningless, only differences between subsequent calls to
2744 this subroutine, as shown in the example below, should be used.
2747 @item @emph{Standard}:
2748 Fortran 95 and later
2750 @item @emph{Class}:
2751 Subroutine
2753 @item @emph{Syntax}:
2754 @code{CALL CPU_TIME(TIME)}
2756 @item @emph{Arguments}:
2757 @multitable @columnfractions .15 .70
2758 @item @var{TIME} @tab The type shall be @code{REAL(*)} with @code{INTENT(OUT)}.
2759 @end multitable
2761 @item @emph{Return value}:
2762 None
2764 @item @emph{Example}:
2765 @smallexample
2766 program test_cpu_time
2767     real :: start, finish
2768     call cpu_time(start)
2769         ! put code to test here
2770     call cpu_time(finish)
2771     print '("Time = ",f6.3," seconds.")',finish-start
2772 end program test_cpu_time
2773 @end smallexample
2775 @item @emph{See also}:
2776 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2777 @end table
2781 @node CSHIFT
2782 @section @code{CSHIFT} --- Circular shift elements of an array
2783 @fnindex CSHIFT
2784 @cindex array, shift circularly
2785 @cindex array, permutation
2786 @cindex array, rotate
2788 @table @asis
2789 @item @emph{Description}:
2790 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2791 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
2792 taken to be @code{1}.  @var{DIM} is a scaler of type @code{INTEGER} in the
2793 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2794 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2795 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
2796 sections of @var{ARRAY} along the given dimension are shifted.  Elements
2797 shifted out one end of each rank one section are shifted back in the other end.
2799 @item @emph{Standard}:
2800 Fortran 95 and later
2802 @item @emph{Class}:
2803 Transformational function
2805 @item @emph{Syntax}:
2806 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2808 @item @emph{Arguments}:
2809 @multitable @columnfractions .15 .70
2810 @item @var{ARRAY}  @tab Shall be an array of any type.
2811 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
2812 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
2813 @end multitable
2815 @item @emph{Return value}:
2816 Returns an array of same type and rank as the @var{ARRAY} argument.
2818 @item @emph{Example}:
2819 @smallexample
2820 program test_cshift
2821     integer, dimension(3,3) :: a
2822     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2823     print '(3i3)', a(1,:)
2824     print '(3i3)', a(2,:)
2825     print '(3i3)', a(3,:)    
2826     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2827     print *
2828     print '(3i3)', a(1,:)
2829     print '(3i3)', a(2,:)
2830     print '(3i3)', a(3,:)
2831 end program test_cshift
2832 @end smallexample
2833 @end table
2837 @node CTIME
2838 @section @code{CTIME} --- Convert a time into a string
2839 @fnindex CTIME
2840 @cindex time, conversion to string
2841 @cindex conversion, to string
2843 @table @asis
2844 @item @emph{Description}:
2845 @code{CTIME} converts a system time value, such as returned by
2846 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2848 This intrinsic is provided in both subroutine and function forms; however,
2849 only one form can be used in any given program unit.
2851 @item @emph{Standard}:
2852 GNU extension
2854 @item @emph{Class}:
2855 Subroutine, function
2857 @item @emph{Syntax}:
2858 @multitable @columnfractions .80
2859 @item @code{CALL CTIME(TIME, RESULT)}.
2860 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2861 @end multitable
2863 @item @emph{Arguments}:
2864 @multitable @columnfractions .15 .70
2865 @item @var{TIME}    @tab The type shall be of type @code{INTEGER(KIND=8)}.
2866 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER}.
2867 @end multitable
2869 @item @emph{Return value}:
2870 The converted date and time as a string.
2872 @item @emph{Example}:
2873 @smallexample
2874 program test_ctime
2875     integer(8) :: i
2876     character(len=30) :: date
2877     i = time8()
2879     ! Do something, main part of the program
2880     
2881     call ctime(i,date)
2882     print *, 'Program was started on ', date
2883 end program test_ctime
2884 @end smallexample
2886 @item @emph{See Also}:
2887 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2888 @end table
2892 @node DATE_AND_TIME
2893 @section @code{DATE_AND_TIME} --- Date and time subroutine
2894 @fnindex DATE_AND_TIME
2895 @cindex date, current
2896 @cindex current date
2897 @cindex time, current
2898 @cindex current time
2900 @table @asis
2901 @item @emph{Description}:
2902 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2903 time information from the real-time system clock.  @var{DATE} is
2904 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
2905 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2906 representing the difference with respect to Coordinated Universal Time (UTC).
2907 Unavailable time and date parameters return blanks.
2909 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2911 @multitable @columnfractions .15 .30 .40
2912 @item @tab @code{VALUE(1)}: @tab The year
2913 @item @tab @code{VALUE(2)}: @tab The month
2914 @item @tab @code{VALUE(3)}: @tab The day of the month
2915 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2916 @item @tab @code{VALUE(5)}: @tab The hour of the day
2917 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2918 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2919 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2920 @end multitable     
2922 @item @emph{Standard}:
2923 Fortran 95 and later
2925 @item @emph{Class}:
2926 Subroutine
2928 @item @emph{Syntax}:
2929 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2931 @item @emph{Arguments}:
2932 @multitable @columnfractions .15 .70
2933 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
2934 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
2935 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
2936 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2937 @end multitable
2939 @item @emph{Return value}:
2940 None
2942 @item @emph{Example}:
2943 @smallexample
2944 program test_time_and_date
2945     character(8)  :: date
2946     character(10) :: time
2947     character(5)  :: zone
2948     integer,dimension(8) :: values
2949     ! using keyword arguments
2950     call date_and_time(date,time,zone,values)
2951     call date_and_time(DATE=date,ZONE=zone)
2952     call date_and_time(TIME=time)
2953     call date_and_time(VALUES=values)
2954     print '(a,2x,a,2x,a)', date, time, zone
2955     print '(8i5))', values
2956 end program test_time_and_date
2957 @end smallexample
2959 @item @emph{See also}:
2960 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
2961 @end table
2965 @node DBLE
2966 @section @code{DBLE} --- Double conversion function 
2967 @fnindex DBLE
2968 @cindex conversion, to real
2970 @table @asis
2971 @item @emph{Description}:
2972 @code{DBLE(X)} Converts @var{X} to double precision real type.
2974 @item @emph{Standard}:
2975 Fortran 77 and later
2977 @item @emph{Class}:
2978 Elemental function
2980 @item @emph{Syntax}:
2981 @code{RESULT = DBLE(X)}
2983 @item @emph{Arguments}:
2984 @multitable @columnfractions .15 .70
2985 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)},
2986                    or @code{COMPLEX(*)}.
2987 @end multitable
2989 @item @emph{Return value}:
2990 The return value is of type double precision real.
2992 @item @emph{Example}:
2993 @smallexample
2994 program test_dble
2995     real    :: x = 2.18
2996     integer :: i = 5
2997     complex :: z = (2.3,1.14)
2998     print *, dble(x), dble(i), dble(z)
2999 end program test_dble
3000 @end smallexample
3002 @item @emph{See also}:
3003 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3004 @end table
3008 @node DCMPLX
3009 @section @code{DCMPLX} --- Double complex conversion function
3010 @fnindex DCMPLX
3011 @cindex complex numbers, conversion to
3012 @cindex conversion, to complex
3014 @table @asis
3015 @item @emph{Description}:
3016 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3017 converted to the real component.  If @var{Y} is present it is converted to the
3018 imaginary component.  If @var{Y} is not present then the imaginary component is
3019 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3021 @item @emph{Standard}:
3022 GNU extension
3024 @item @emph{Class}:
3025 Elemental function
3027 @item @emph{Syntax}:
3028 @code{RESULT = DCMPLX(X [, Y])}
3030 @item @emph{Arguments}:
3031 @multitable @columnfractions .15 .70
3032 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
3033                    or @code{COMPLEX(*)}.
3034 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX(*)}.) May be
3035                    @code{INTEGER(*)} or @code{REAL(*)}. 
3036 @end multitable
3038 @item @emph{Return value}:
3039 The return value is of type @code{COMPLEX(8)}
3041 @item @emph{Example}:
3042 @smallexample
3043 program test_dcmplx
3044     integer :: i = 42
3045     real :: x = 3.14
3046     complex :: z
3047     z = cmplx(i, x)
3048     print *, dcmplx(i)
3049     print *, dcmplx(x)
3050     print *, dcmplx(z)
3051     print *, dcmplx(x,i)
3052 end program test_dcmplx
3053 @end smallexample
3054 @end table
3058 @node DFLOAT
3059 @section @code{DFLOAT} --- Double conversion function 
3060 @fnindex DFLOAT
3061 @cindex conversion, to real
3063 @table @asis
3064 @item @emph{Description}:
3065 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
3067 @item @emph{Standard}:
3068 GNU extension
3070 @item @emph{Class}:
3071 Elemental function
3073 @item @emph{Syntax}:
3074 @code{RESULT = DFLOAT(X)}
3076 @item @emph{Arguments}:
3077 @multitable @columnfractions .15 .70
3078 @item @var{X} @tab The type shall be @code{INTEGER(*)}.
3079 @end multitable
3081 @item @emph{Return value}:
3082 The return value is of type double precision real.
3084 @item @emph{Example}:
3085 @smallexample
3086 program test_dfloat
3087     integer :: i = 5
3088     print *, dfloat(i)
3089 end program test_dfloat
3090 @end smallexample
3092 @item @emph{See also}:
3093 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3094 @end table
3098 @node DIGITS
3099 @section @code{DIGITS} --- Significant digits function
3100 @fnindex DIGITS
3101 @cindex model representation, significant digits
3103 @table @asis
3104 @item @emph{Description}:
3105 @code{DIGITS(X)} returns the number of significant digits of the internal model
3106 representation of @var{X}.  For example, on a system using a 32-bit
3107 floating point representation, a default real number would likely return 24.
3109 @item @emph{Standard}:
3110 Fortran 95 and later
3112 @item @emph{Class}:
3113 Inquiry function
3115 @item @emph{Syntax}:
3116 @code{RESULT = DIGITS(X)}
3118 @item @emph{Arguments}:
3119 @multitable @columnfractions .15 .70
3120 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
3121 @end multitable
3123 @item @emph{Return value}:
3124 The return value is of type @code{INTEGER}.
3126 @item @emph{Example}:
3127 @smallexample
3128 program test_digits
3129     integer :: i = 12345
3130     real :: x = 3.143
3131     real(8) :: y = 2.33
3132     print *, digits(i)
3133     print *, digits(x)
3134     print *, digits(y)
3135 end program test_digits
3136 @end smallexample
3137 @end table
3141 @node DIM
3142 @section @code{DIM} --- Positive difference
3143 @fnindex DIM
3144 @fnindex IDIM
3145 @fnindex DDIM
3146 @cindex positive difference
3148 @table @asis
3149 @item @emph{Description}:
3150 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3151 otherwise returns zero.
3153 @item @emph{Standard}:
3154 Fortran 77 and later
3156 @item @emph{Class}:
3157 Elemental function
3159 @item @emph{Syntax}:
3160 @code{RESULT = DIM(X, Y)}
3162 @item @emph{Arguments}:
3163 @multitable @columnfractions .15 .70
3164 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
3165 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3166 @end multitable
3168 @item @emph{Return value}:
3169 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
3171 @item @emph{Example}:
3172 @smallexample
3173 program test_dim
3174     integer :: i
3175     real(8) :: x
3176     i = dim(4, 15)
3177     x = dim(4.345_8, 2.111_8)
3178     print *, i
3179     print *, x
3180 end program test_dim
3181 @end smallexample
3183 @item @emph{Specific names}:
3184 @multitable @columnfractions .20 .20 .20 .25
3185 @item Name             @tab Argument              @tab Return type       @tab Standard
3186 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3187 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3188 @end multitable
3189 @end table
3193 @node DOT_PRODUCT
3194 @section @code{DOT_PRODUCT} --- Dot product function
3195 @fnindex DOT_PRODUCT
3196 @cindex dot product
3197 @cindex vector product
3198 @cindex product, vector
3200 @table @asis
3201 @item @emph{Description}:
3202 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
3203 @var{X} and @var{Y}.  The two vectors may be either numeric or logical
3204 and must be arrays of rank one and of equal size. If the vectors are
3205 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
3206 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the 
3207 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
3209 @item @emph{Standard}:
3210 Fortran 95 and later
3212 @item @emph{Class}:
3213 Transformational function
3215 @item @emph{Syntax}:
3216 @code{RESULT = DOT_PRODUCT(X, Y)}
3218 @item @emph{Arguments}:
3219 @multitable @columnfractions .15 .70
3220 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3221 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3222 @end multitable
3224 @item @emph{Return value}:
3225 If the arguments are numeric, the return value is a scaler of numeric type,
3226 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}.  If the arguments are
3227 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3229 @item @emph{Example}:
3230 @smallexample
3231 program test_dot_prod
3232     integer, dimension(3) :: a, b
3233     a = (/ 1, 2, 3 /)
3234     b = (/ 4, 5, 6 /)
3235     print '(3i3)', a
3236     print *
3237     print '(3i3)', b
3238     print *
3239     print *, dot_product(a,b)
3240 end program test_dot_prod
3241 @end smallexample
3242 @end table
3246 @node DPROD
3247 @section @code{DPROD} --- Double product function
3248 @fnindex DPROD
3249 @cindex product, double-precision
3251 @table @asis
3252 @item @emph{Description}:
3253 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3255 @item @emph{Standard}:
3256 Fortran 77 and later
3258 @item @emph{Class}:
3259 Elemental function
3261 @item @emph{Syntax}:
3262 @code{RESULT = DPROD(X, Y)}
3264 @item @emph{Arguments}:
3265 @multitable @columnfractions .15 .70
3266 @item @var{X} @tab The type shall be @code{REAL}.
3267 @item @var{Y} @tab The type shall be @code{REAL}.
3268 @end multitable
3270 @item @emph{Return value}:
3271 The return value is of type @code{REAL(8)}.
3273 @item @emph{Example}:
3274 @smallexample
3275 program test_dprod
3276     real :: x = 5.2
3277     real :: y = 2.3
3278     real(8) :: d
3279     d = dprod(x,y)
3280     print *, d
3281 end program test_dprod
3282 @end smallexample
3283 @end table
3287 @node DREAL
3288 @section @code{DREAL} --- Double real part function
3289 @fnindex DREAL
3290 @cindex complex numbers, real part
3292 @table @asis
3293 @item @emph{Description}:
3294 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3296 @item @emph{Standard}:
3297 GNU extension
3299 @item @emph{Class}:
3300 Elemental function
3302 @item @emph{Syntax}:
3303 @code{RESULT = DREAL(Z)}
3305 @item @emph{Arguments}:
3306 @multitable @columnfractions .15 .70
3307 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
3308 @end multitable
3310 @item @emph{Return value}:
3311 The return value is of type @code{REAL(8)}.
3313 @item @emph{Example}:
3314 @smallexample
3315 program test_dreal
3316     complex(8) :: z = (1.3_8,7.2_8)
3317     print *, dreal(z)
3318 end program test_dreal
3319 @end smallexample
3321 @item @emph{See also}:
3322 @ref{AIMAG}
3324 @end table
3328 @node DTIME
3329 @section @code{DTIME} --- Execution time subroutine (or function)
3330 @fnindex DTIME
3331 @cindex time, elapsed
3332 @cindex elapsed time
3334 @table @asis
3335 @item @emph{Description}:
3336 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3337 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
3338 returns the user and system components of this time in @code{TARRAY(1)} and
3339 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3340 TARRAY(2)}.
3342 Subsequent invocations of @code{DTIME} return values accumulated since the
3343 previous invocation.
3345 On some systems, the underlying timings are represented using types with
3346 sufficiently small limits that overflows (wrap around) are possible, such as
3347 32-bit types. Therefore, the values returned by this intrinsic might be, or
3348 become, negative, or numerically less than previous values, during a single
3349 run of the compiled program.
3351 Please note, that this implementation is thread safe if used within OpenMP
3352 directives, i.e., its state will be consistent while called from multiple
3353 threads. However, if @code{DTIME} is called from multiple threads, the result
3354 is still the time since the last invocation. This may not give the intended
3355 results. If possible, use @code{CPU_TIME} instead.
3357 This intrinsic is provided in both subroutine and function forms; however,
3358 only one form can be used in any given program unit.
3360 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3362 @multitable @columnfractions .15 .30 .40
3363 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3364 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3365 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3366 @end multitable
3368 @item @emph{Standard}:
3369 GNU extension
3371 @item @emph{Class}:
3372 Subroutine, function
3374 @item @emph{Syntax}:
3375 @multitable @columnfractions .80
3376 @item @code{CALL DTIME(TARRAY, RESULT)}.
3377 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3378 @end multitable
3380 @item @emph{Arguments}:
3381 @multitable @columnfractions .15 .70
3382 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3383 @item @var{RESULT}@tab The type shall be @code{REAL}.
3384 @end multitable
3386 @item @emph{Return value}:
3387 Elapsed time in seconds since the last invocation or since the start of program
3388 execution if not called before.
3390 @item @emph{Example}:
3391 @smallexample
3392 program test_dtime
3393     integer(8) :: i, j
3394     real, dimension(2) :: tarray
3395     real :: result
3396     call dtime(tarray, result)
3397     print *, result
3398     print *, tarray(1)
3399     print *, tarray(2)   
3400     do i=1,100000000    ! Just a delay
3401         j = i * i - i
3402     end do
3403     call dtime(tarray, result)
3404     print *, result
3405     print *, tarray(1)
3406     print *, tarray(2)
3407 end program test_dtime
3408 @end smallexample
3410 @item @emph{See also}:
3411 @ref{CPU_TIME}
3413 @end table
3417 @node EOSHIFT
3418 @section @code{EOSHIFT} --- End-off shift elements of an array
3419 @fnindex EOSHIFT
3420 @cindex array, shift
3422 @table @asis
3423 @item @emph{Description}:
3424 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
3425 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3426 omitted it is taken to be @code{1}.  @var{DIM} is a scaler of type
3427 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3428 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3429 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3430 then all complete rank one sections of @var{ARRAY} along the given dimension are
3431 shifted.  Elements shifted out one end of each rank one section are dropped.  If
3432 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3433 is copied back in the other end.  If @var{BOUNDARY} is not present then the
3434 following are copied in depending on the type of @var{ARRAY}.
3436 @multitable @columnfractions .15 .80
3437 @item @emph{Array Type} @tab @emph{Boundary Value}
3438 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3439 @item Logical  @tab @code{.FALSE.}.
3440 @item Character(@var{len}) @tab @var{len} blanks.
3441 @end multitable
3443 @item @emph{Standard}:
3444 Fortran 95 and later
3446 @item @emph{Class}:
3447 Transformational function
3449 @item @emph{Syntax}:
3450 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3452 @item @emph{Arguments}:
3453 @multitable @columnfractions .15 .70
3454 @item @var{ARRAY}  @tab May be any type, not scaler.
3455 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3456 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}. 
3457 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3458 @end multitable
3460 @item @emph{Return value}:
3461 Returns an array of same type and rank as the @var{ARRAY} argument.
3463 @item @emph{Example}:
3464 @smallexample
3465 program test_eoshift
3466     integer, dimension(3,3) :: a
3467     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3468     print '(3i3)', a(1,:)
3469     print '(3i3)', a(2,:)
3470     print '(3i3)', a(3,:)    
3471     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3472     print *
3473     print '(3i3)', a(1,:)
3474     print '(3i3)', a(2,:)
3475     print '(3i3)', a(3,:)
3476 end program test_eoshift
3477 @end smallexample
3478 @end table
3482 @node EPSILON
3483 @section @code{EPSILON} --- Epsilon function
3484 @fnindex EPSILON
3485 @cindex model representation, epsilon
3487 @table @asis
3488 @item @emph{Description}:
3489 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3491 @item @emph{Standard}:
3492 Fortran 95 and later
3494 @item @emph{Class}:
3495 Inquiry function
3497 @item @emph{Syntax}:
3498 @code{RESULT = EPSILON(X)}
3500 @item @emph{Arguments}:
3501 @multitable @columnfractions .15 .70
3502 @item @var{X} @tab The type shall be @code{REAL(*)}.
3503 @end multitable
3505 @item @emph{Return value}:
3506 The return value is of same type as the argument.
3508 @item @emph{Example}:
3509 @smallexample
3510 program test_epsilon
3511     real :: x = 3.143
3512     real(8) :: y = 2.33
3513     print *, EPSILON(x)
3514     print *, EPSILON(y)
3515 end program test_epsilon
3516 @end smallexample
3517 @end table
3521 @node ERF
3522 @section @code{ERF} --- Error function 
3523 @fnindex ERF
3524 @cindex error function
3526 @table @asis
3527 @item @emph{Description}:
3528 @code{ERF(X)} computes the error function of @var{X}.
3530 @item @emph{Standard}:
3531 Fortran 2008 and later
3533 @item @emph{Class}:
3534 Elemental function
3536 @item @emph{Syntax}:
3537 @code{RESULT = ERF(X)}
3539 @item @emph{Arguments}:
3540 @multitable @columnfractions .15 .70
3541 @item @var{X} @tab The type shall be @code{REAL}.
3542 @end multitable
3544 @item @emph{Return value}:
3545 The return value is of type @code{REAL}, of the same kind as
3546 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3548 @item @emph{Example}:
3549 @smallexample
3550 program test_erf
3551   real(8) :: x = 0.17_8
3552   x = erf(x)
3553 end program test_erf
3554 @end smallexample
3556 @item @emph{Specific names}:
3557 @multitable @columnfractions .20 .20 .20 .25
3558 @item Name            @tab Argument          @tab Return type       @tab Standard
3559 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3560 @end multitable
3561 @end table
3565 @node ERFC
3566 @section @code{ERFC} --- Error function 
3567 @fnindex ERFC
3568 @cindex error function, complementary
3570 @table @asis
3571 @item @emph{Description}:
3572 @code{ERFC(X)} computes the complementary error function of @var{X}.
3574 @item @emph{Standard}:
3575 Fortran 2008 and later
3577 @item @emph{Class}:
3578 Elemental function
3580 @item @emph{Syntax}:
3581 @code{RESULT = ERFC(X)}
3583 @item @emph{Arguments}:
3584 @multitable @columnfractions .15 .70
3585 @item @var{X} @tab The type shall be @code{REAL}.
3586 @end multitable
3588 @item @emph{Return value}:
3589 The return value is of type @code{REAL} and of the same kind as @var{X}.
3590 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3592 @item @emph{Example}:
3593 @smallexample
3594 program test_erfc
3595   real(8) :: x = 0.17_8
3596   x = erfc(x)
3597 end program test_erfc
3598 @end smallexample
3600 @item @emph{Specific names}:
3601 @multitable @columnfractions .20 .20 .20 .25
3602 @item Name            @tab Argument          @tab Return type       @tab Standard
3603 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3604 @end multitable
3605 @end table
3609 @node ERFC_SCALED
3610 @section @code{ERFC_SCALED} --- Error function 
3611 @fnindex ERFC_SCALED
3612 @cindex error function, complementary, exponentially-scaled
3614 @table @asis
3615 @item @emph{Description}:
3616 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3617 error function of @var{X}.
3619 @item @emph{Standard}:
3620 Fortran 2008 and later
3622 @item @emph{Class}:
3623 Elemental function
3625 @item @emph{Syntax}:
3626 @code{RESULT = ERFC_SCALED(X)}
3628 @item @emph{Arguments}:
3629 @multitable @columnfractions .15 .70
3630 @item @var{X} @tab The type shall be @code{REAL}.
3631 @end multitable
3633 @item @emph{Return value}:
3634 The return value is of type @code{REAL} and of the same kind as @var{X}.
3636 @item @emph{Example}:
3637 @smallexample
3638 program test_erfc_scaled
3639   real(8) :: x = 0.17_8
3640   x = erfc_scaled(x)
3641 end program test_erfc_scaled
3642 @end smallexample
3643 @end table
3647 @node ETIME
3648 @section @code{ETIME} --- Execution time subroutine (or function)
3649 @fnindex ETIME
3650 @cindex time, elapsed
3652 @table @asis
3653 @item @emph{Description}:
3654 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3655 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
3656 returns the user and system components of this time in @code{TARRAY(1)} and
3657 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3659 On some systems, the underlying timings are represented using types with
3660 sufficiently small limits that overflows (wrap around) are possible, such as
3661 32-bit types. Therefore, the values returned by this intrinsic might be, or
3662 become, negative, or numerically less than previous values, during a single
3663 run of the compiled program.
3665 This intrinsic is provided in both subroutine and function forms; however,
3666 only one form can be used in any given program unit.
3668 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3670 @multitable @columnfractions .15 .30 .60
3671 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3672 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3673 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3674 @end multitable
3676 @item @emph{Standard}:
3677 GNU extension
3679 @item @emph{Class}:
3680 Subroutine, function
3682 @item @emph{Syntax}:
3683 @multitable @columnfractions .80
3684 @item @code{CALL ETIME(TARRAY, RESULT)}.
3685 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3686 @end multitable
3688 @item @emph{Arguments}:
3689 @multitable @columnfractions .15 .70
3690 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3691 @item @var{RESULT}@tab The type shall be @code{REAL}.
3692 @end multitable
3694 @item @emph{Return value}:
3695 Elapsed time in seconds since the start of program execution.
3697 @item @emph{Example}:
3698 @smallexample
3699 program test_etime
3700     integer(8) :: i, j
3701     real, dimension(2) :: tarray
3702     real :: result
3703     call ETIME(tarray, result)
3704     print *, result
3705     print *, tarray(1)
3706     print *, tarray(2)   
3707     do i=1,100000000    ! Just a delay
3708         j = i * i - i
3709     end do
3710     call ETIME(tarray, result)
3711     print *, result
3712     print *, tarray(1)
3713     print *, tarray(2)
3714 end program test_etime
3715 @end smallexample
3717 @item @emph{See also}:
3718 @ref{CPU_TIME}
3720 @end table
3724 @node EXIT
3725 @section @code{EXIT} --- Exit the program with status. 
3726 @fnindex EXIT
3727 @cindex program termination
3728 @cindex terminate program
3730 @table @asis
3731 @item @emph{Description}:
3732 @code{EXIT} causes immediate termination of the program with status.  If status
3733 is omitted it returns the canonical @emph{success} for the system.  All Fortran
3734 I/O units are closed. 
3736 @item @emph{Standard}:
3737 GNU extension
3739 @item @emph{Class}:
3740 Subroutine
3742 @item @emph{Syntax}:
3743 @code{CALL EXIT([STATUS])}
3745 @item @emph{Arguments}:
3746 @multitable @columnfractions .15 .70
3747 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3748 @end multitable
3750 @item @emph{Return value}:
3751 @code{STATUS} is passed to the parent process on exit.
3753 @item @emph{Example}:
3754 @smallexample
3755 program test_exit
3756   integer :: STATUS = 0
3757   print *, 'This program is going to exit.'
3758   call EXIT(STATUS)
3759 end program test_exit
3760 @end smallexample
3762 @item @emph{See also}:
3763 @ref{ABORT}, @ref{KILL}
3764 @end table
3768 @node EXP
3769 @section @code{EXP} --- Exponential function 
3770 @fnindex EXP
3771 @fnindex DEXP
3772 @fnindex CEXP
3773 @fnindex ZEXP
3774 @fnindex CDEXP
3775 @cindex exponential function
3776 @cindex logarithmic function, inverse
3778 @table @asis
3779 @item @emph{Description}:
3780 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3782 @item @emph{Standard}:
3783 Fortran 77 and later, has overloads that are GNU extensions
3785 @item @emph{Class}:
3786 Elemental function
3788 @item @emph{Syntax}:
3789 @code{RESULT = EXP(X)}
3791 @item @emph{Arguments}:
3792 @multitable @columnfractions .15 .70
3793 @item @var{X} @tab The type shall be @code{REAL(*)} or
3794 @code{COMPLEX(*)}.
3795 @end multitable
3797 @item @emph{Return value}:
3798 The return value has same type and kind as @var{X}.
3800 @item @emph{Example}:
3801 @smallexample
3802 program test_exp
3803   real :: x = 1.0
3804   x = exp(x)
3805 end program test_exp
3806 @end smallexample
3808 @item @emph{Specific names}:
3809 @multitable @columnfractions .20 .20 .20 .25
3810 @item Name            @tab Argument             @tab Return type         @tab Standard
3811 @item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
3812 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
3813 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3814 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3815 @end multitable
3816 @end table
3820 @node EXPONENT
3821 @section @code{EXPONENT} --- Exponent function 
3822 @fnindex EXPONENT
3823 @cindex real number, exponent
3824 @cindex floating point, exponent
3826 @table @asis
3827 @item @emph{Description}:
3828 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3829 is zero the value returned is zero. 
3831 @item @emph{Standard}:
3832 Fortran 95 and later
3834 @item @emph{Class}:
3835 Elemental function
3837 @item @emph{Syntax}:
3838 @code{RESULT = EXPONENT(X)}
3840 @item @emph{Arguments}:
3841 @multitable @columnfractions .15 .70
3842 @item @var{X} @tab The type shall be @code{REAL(*)}.
3843 @end multitable
3845 @item @emph{Return value}:
3846 The return value is of type default @code{INTEGER}.
3848 @item @emph{Example}:
3849 @smallexample
3850 program test_exponent
3851   real :: x = 1.0
3852   integer :: i
3853   i = exponent(x)
3854   print *, i
3855   print *, exponent(0.0)
3856 end program test_exponent
3857 @end smallexample
3858 @end table
3862 @node FDATE
3863 @section @code{FDATE} --- Get the current time as a string
3864 @fnindex FDATE
3865 @cindex time, current
3866 @cindex current time
3867 @cindex date, current
3868 @cindex current date
3870 @table @asis
3871 @item @emph{Description}:
3872 @code{FDATE(DATE)} returns the current date (using the same format as
3873 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3874 TIME())}.
3876 This intrinsic is provided in both subroutine and function forms; however,
3877 only one form can be used in any given program unit.
3879 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
3881 @item @emph{Standard}:
3882 GNU extension
3884 @item @emph{Class}:
3885 Subroutine, function
3887 @item @emph{Syntax}:
3888 @multitable @columnfractions .80
3889 @item @code{CALL FDATE(DATE)}.
3890 @item @code{DATE = FDATE()}, (not recommended).
3891 @end multitable
3893 @item @emph{Arguments}:
3894 @multitable @columnfractions .15 .70
3895 @item @var{DATE}@tab The type shall be of type @code{CHARACTER}.
3896 @end multitable
3898 @item @emph{Return value}:
3899 The current date as a string.
3901 @item @emph{Example}:
3902 @smallexample
3903 program test_fdate
3904     integer(8) :: i, j
3905     character(len=30) :: date
3906     call fdate(date)
3907     print *, 'Program started on ', date
3908     do i = 1, 100000000 ! Just a delay
3909         j = i * i - i
3910     end do
3911     call fdate(date)
3912     print *, 'Program ended on ', date
3913 end program test_fdate
3914 @end smallexample
3915 @end table
3919 @node FLOAT
3920 @section @code{FLOAT} --- Convert integer to default real
3921 @fnindex FLOAT
3922 @cindex conversion, to real
3924 @table @asis
3925 @item @emph{Description}:
3926 @code{FLOAT(I)} converts the integer @var{I} to a default real value.
3928 @item @emph{Standard}:
3929 Fortran 77 and later
3931 @item @emph{Class}:
3932 Elemental function
3934 @item @emph{Syntax}:
3935 @code{RESULT = FLOAT(I)}
3937 @item @emph{Arguments}:
3938 @multitable @columnfractions .15 .70
3939 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
3940 @end multitable
3942 @item @emph{Return value}:
3943 The return value is of type default @code{REAL}.
3945 @item @emph{Example}:
3946 @smallexample
3947 program test_float
3948     integer :: i = 1
3949     if (float(i) /= 1.) call abort
3950 end program test_float
3951 @end smallexample
3953 @item @emph{See also}:
3954 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3955 @end table
3959 @node FGET
3960 @section @code{FGET} --- Read a single character in stream mode from stdin 
3961 @fnindex FGET
3962 @cindex read character, stream mode
3963 @cindex stream mode, read character
3964 @cindex file operation, read character
3966 @table @asis
3967 @item @emph{Description}:
3968 Read a single character in stream mode from stdin by bypassing normal 
3969 formatted output. Stream I/O should not be mixed with normal record-oriented 
3970 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3972 This intrinsic is provided in both subroutine and function forms; however,
3973 only one form can be used in any given program unit.
3975 Note that the @code{FGET} intrinsic is provided for backwards compatibility with 
3976 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
3977 Programmers should consider the use of new stream IO feature in new code 
3978 for future portability. See also @ref{Fortran 2003 status}.
3980 @item @emph{Standard}:
3981 GNU extension
3983 @item @emph{Class}:
3984 Subroutine, function
3986 @item @emph{Syntax}:
3987 @code{CALL FGET(C [, STATUS])}
3989 @item @emph{Arguments}:
3990 @multitable @columnfractions .15 .70
3991 @item @var{C}      @tab The type shall be @code{CHARACTER}.
3992 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
3993                         Returns 0 on success, -1 on end-of-file, and a
3994                         system specific positive error code otherwise.
3995 @end multitable
3997 @item @emph{Example}:
3998 @smallexample
3999 PROGRAM test_fget
4000   INTEGER, PARAMETER :: strlen = 100
4001   INTEGER :: status, i = 1
4002   CHARACTER(len=strlen) :: str = ""
4004   WRITE (*,*) 'Enter text:'
4005   DO
4006     CALL fget(str(i:i), status)
4007     if (status /= 0 .OR. i > strlen) exit
4008     i = i + 1
4009   END DO
4010   WRITE (*,*) TRIM(str)
4011 END PROGRAM
4012 @end smallexample
4014 @item @emph{See also}:
4015 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4016 @end table
4020 @node FGETC
4021 @section @code{FGETC} --- Read a single character in stream mode
4022 @fnindex FGETC
4023 @cindex read character, stream mode
4024 @cindex stream mode, read character
4025 @cindex file operation, read character
4027 @table @asis
4028 @item @emph{Description}:
4029 Read a single character in stream mode by bypassing normal formatted output. 
4030 Stream I/O should not be mixed with normal record-oriented (formatted or 
4031 unformatted) I/O on the same unit; the results are unpredictable.
4033 This intrinsic is provided in both subroutine and function forms; however,
4034 only one form can be used in any given program unit.
4036 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4037 with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4038 Programmers should consider the use of new stream IO feature in new code 
4039 for future portability. See also @ref{Fortran 2003 status}.
4041 @item @emph{Standard}:
4042 GNU extension
4044 @item @emph{Class}:
4045 Subroutine, function
4047 @item @emph{Syntax}:
4048 @code{CALL FGETC(UNIT, C [, STATUS])}
4050 @item @emph{Arguments}:
4051 @multitable @columnfractions .15 .70
4052 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4053 @item @var{C}      @tab The type shall be @code{CHARACTER}.
4054 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4055                         -1 on end-of-file and a system specific positive error code otherwise.
4056 @end multitable
4058 @item @emph{Example}:
4059 @smallexample
4060 PROGRAM test_fgetc
4061   INTEGER :: fd = 42, status
4062   CHARACTER :: c
4064   OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4065   DO
4066     CALL fgetc(fd, c, status)
4067     IF (status /= 0) EXIT
4068     call fput(c)
4069   END DO
4070   CLOSE(UNIT=fd)
4071 END PROGRAM
4072 @end smallexample
4074 @item @emph{See also}:
4075 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4076 @end table
4080 @node FLOOR
4081 @section @code{FLOOR} --- Integer floor function
4082 @fnindex FLOOR
4083 @cindex floor
4084 @cindex rounding, floor
4086 @table @asis
4087 @item @emph{Description}:
4088 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
4090 @item @emph{Standard}:
4091 Fortran 95 and later
4093 @item @emph{Class}:
4094 Elemental function
4096 @item @emph{Syntax}:
4097 @code{RESULT = FLOOR(X [, KIND])}
4099 @item @emph{Arguments}:
4100 @multitable @columnfractions .15 .70
4101 @item @var{X} @tab The type shall be @code{REAL(*)}.
4102 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
4103                       expression indicating the kind parameter of
4104                       the result.
4105 @end multitable
4107 @item @emph{Return value}:
4108 The return value is of type @code{INTEGER(KIND)}
4110 @item @emph{Example}:
4111 @smallexample
4112 program test_floor
4113     real :: x = 63.29
4114     real :: y = -63.59
4115     print *, floor(x) ! returns 63
4116     print *, floor(y) ! returns -64
4117 end program test_floor
4118 @end smallexample
4120 @item @emph{See also}:
4121 @ref{CEILING}, @ref{NINT}
4123 @end table
4127 @node FLUSH
4128 @section @code{FLUSH} --- Flush I/O unit(s)
4129 @fnindex FLUSH
4130 @cindex file operation, flush
4132 @table @asis
4133 @item @emph{Description}:
4134 Flushes Fortran unit(s) currently open for output. Without the optional
4135 argument, all units are flushed, otherwise just the unit specified.
4137 @item @emph{Standard}:
4138 GNU extension
4140 @item @emph{Class}:
4141 Subroutine
4143 @item @emph{Syntax}:
4144 @code{CALL FLUSH(UNIT)}
4146 @item @emph{Arguments}:
4147 @multitable @columnfractions .15 .70
4148 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4149 @end multitable
4151 @item @emph{Note}:
4152 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4153 statement that should be preferred over the @code{FLUSH} intrinsic.
4155 @end table
4159 @node FNUM
4160 @section @code{FNUM} --- File number function
4161 @fnindex FNUM
4162 @cindex file operation, file number
4164 @table @asis
4165 @item @emph{Description}:
4166 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4167 open Fortran I/O unit @code{UNIT}.
4169 @item @emph{Standard}:
4170 GNU extension
4172 @item @emph{Class}:
4173 Function
4175 @item @emph{Syntax}:
4176 @code{RESULT = FNUM(UNIT)}
4178 @item @emph{Arguments}:
4179 @multitable @columnfractions .15 .70
4180 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4181 @end multitable
4183 @item @emph{Return value}:
4184 The return value is of type @code{INTEGER}
4186 @item @emph{Example}:
4187 @smallexample
4188 program test_fnum
4189   integer :: i
4190   open (unit=10, status = "scratch")
4191   i = fnum(10)
4192   print *, i
4193   close (10)
4194 end program test_fnum
4195 @end smallexample
4196 @end table
4200 @node FPUT
4201 @section @code{FPUT} --- Write a single character in stream mode to stdout 
4202 @fnindex FPUT
4203 @cindex write character, stream mode
4204 @cindex stream mode, write character
4205 @cindex file operation, write character
4207 @table @asis
4208 @item @emph{Description}:
4209 Write a single character in stream mode to stdout by bypassing normal 
4210 formatted output. Stream I/O should not be mixed with normal record-oriented 
4211 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4213 This intrinsic is provided in both subroutine and function forms; however,
4214 only one form can be used in any given program unit.
4216 Note that the @code{FGET} intrinsic is provided for backwards compatibility with 
4217 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4218 Programmers should consider the use of new stream IO feature in new code 
4219 for future portability. See also @ref{Fortran 2003 status}.
4221 @item @emph{Standard}:
4222 GNU extension
4224 @item @emph{Class}:
4225 Subroutine, function
4227 @item @emph{Syntax}:
4228 @code{CALL FPUT(C [, STATUS])}
4230 @item @emph{Arguments}:
4231 @multitable @columnfractions .15 .70
4232 @item @var{C}      @tab The type shall be @code{CHARACTER}.
4233 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4234                         -1 on end-of-file and a system specific positive error code otherwise.
4235 @end multitable
4237 @item @emph{Example}:
4238 @smallexample
4239 PROGRAM test_fput
4240   CHARACTER(len=10) :: str = "gfortran"
4241   INTEGER :: i
4242   DO i = 1, len_trim(str)
4243     CALL fput(str(i:i))
4244   END DO
4245 END PROGRAM
4246 @end smallexample
4248 @item @emph{See also}:
4249 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4250 @end table
4254 @node FPUTC
4255 @section @code{FPUTC} --- Write a single character in stream mode
4256 @fnindex FPUTC
4257 @cindex write character, stream mode
4258 @cindex stream mode, write character
4259 @cindex file operation, write character
4261 @table @asis
4262 @item @emph{Description}:
4263 Write a single character in stream mode by bypassing normal formatted 
4264 output. Stream I/O should not be mixed with normal record-oriented 
4265 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4267 This intrinsic is provided in both subroutine and function forms; however,
4268 only one form can be used in any given program unit.
4270 Note that the @code{FGET} intrinsic is provided for backwards compatibility with 
4271 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4272 Programmers should consider the use of new stream IO feature in new code 
4273 for future portability. See also @ref{Fortran 2003 status}.
4275 @item @emph{Standard}:
4276 GNU extension
4278 @item @emph{Class}:
4279 Subroutine, function
4281 @item @emph{Syntax}:
4282 @code{CALL FPUTC(UNIT, C [, STATUS])}
4284 @item @emph{Arguments}:
4285 @multitable @columnfractions .15 .70
4286 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4287 @item @var{C}      @tab The type shall be @code{CHARACTER}.
4288 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4289                         -1 on end-of-file and a system specific positive error code otherwise.
4290 @end multitable
4292 @item @emph{Example}:
4293 @smallexample
4294 PROGRAM test_fputc
4295   CHARACTER(len=10) :: str = "gfortran"
4296   INTEGER :: fd = 42, i
4298   OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4299   DO i = 1, len_trim(str)
4300     CALL fputc(fd, str(i:i))
4301   END DO
4302   CLOSE(fd)
4303 END PROGRAM
4304 @end smallexample
4306 @item @emph{See also}:
4307 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4308 @end table
4312 @node FRACTION
4313 @section @code{FRACTION} --- Fractional part of the model representation
4314 @fnindex FRACTION
4315 @cindex real number, fraction
4316 @cindex floating point, fraction
4318 @table @asis
4319 @item @emph{Description}:
4320 @code{FRACTION(X)} returns the fractional part of the model
4321 representation of @code{X}.
4323 @item @emph{Standard}:
4324 Fortran 95 and later
4326 @item @emph{Class}:
4327 Elemental function
4329 @item @emph{Syntax}:
4330 @code{Y = FRACTION(X)}
4332 @item @emph{Arguments}:
4333 @multitable @columnfractions .15 .70
4334 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4335 @end multitable
4337 @item @emph{Return value}:
4338 The return value is of the same type and kind as the argument.
4339 The fractional part of the model representation of @code{X} is returned;
4340 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4342 @item @emph{Example}:
4343 @smallexample
4344 program test_fraction
4345   real :: x
4346   x = 178.1387e-4
4347   print *, fraction(x), x * radix(x)**(-exponent(x))
4348 end program test_fraction
4349 @end smallexample
4351 @end table
4355 @node FREE
4356 @section @code{FREE} --- Frees memory
4357 @fnindex FREE
4358 @cindex pointer, cray
4360 @table @asis
4361 @item @emph{Description}:
4362 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4363 intrinsic is an extension intended to be used with Cray pointers, and is
4364 provided in GNU Fortran to allow user to compile legacy code. For
4365 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4366 @code{DEALLOCATE}.
4368 @item @emph{Standard}:
4369 GNU extension
4371 @item @emph{Class}:
4372 Subroutine
4374 @item @emph{Syntax}:
4375 @code{CALL FREE(PTR)}
4377 @item @emph{Arguments}:
4378 @multitable @columnfractions .15 .70
4379 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4380 location of the memory that should be de-allocated.
4381 @end multitable
4383 @item @emph{Return value}:
4384 None
4386 @item @emph{Example}:
4387 See @code{MALLOC} for an example.
4389 @item @emph{See also}:
4390 @ref{MALLOC}
4391 @end table
4395 @node FSEEK
4396 @section @code{FSEEK} --- Low level file positioning subroutine
4397 @fnindex FSEEK
4398 @cindex file operation, seek
4399 @cindex file operation, position
4401 @table @asis
4402 @item @emph{Description}:
4403 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} 
4404 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4405 if set to 1, @var{OFFSET} is taken to be relative to the current position 
4406 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4407 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek 
4408 fails silently.
4410 This intrinsic routine is not fully backwards compatible with @command{g77}. 
4411 In @command{g77}, the @code{FSEEK} takes a statement label instead of a 
4412 @var{STATUS} variable. If FSEEK is used in old code, change
4413 @smallexample
4414   CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4415 @end smallexample 
4417 @smallexample
4418   INTEGER :: status
4419   CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4420   IF (status /= 0) GOTO label
4421 @end smallexample 
4423 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4424 Programmers should consider the use of new stream IO feature in new code 
4425 for future portability. See also @ref{Fortran 2003 status}.
4427 @item @emph{Standard}:
4428 GNU extension
4430 @item @emph{Class}:
4431 Subroutine
4433 @item @emph{Syntax}:
4434 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4436 @item @emph{Arguments}:
4437 @multitable @columnfractions .15 .70
4438 @item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
4439 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4440 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4441 Its value shall be either 0, 1 or 2.
4442 @item @var{STATUS} @tab (Optional) shall be a scalar of type 
4443 @code{INTEGER(4)}.
4444 @end multitable
4446 @item @emph{Example}:
4447 @smallexample
4448 PROGRAM test_fseek
4449   INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4450   INTEGER :: fd, offset, ierr
4452   ierr   = 0
4453   offset = 5
4454   fd     = 10
4456   OPEN(UNIT=fd, FILE="fseek.test")
4457   CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
4458   print *, FTELL(fd), ierr
4460   CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
4461   print *, FTELL(fd), ierr
4463   CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
4464   print *, FTELL(fd), ierr
4466   CLOSE(UNIT=fd)
4467 END PROGRAM
4468 @end smallexample
4470 @item @emph{See also}:
4471 @ref{FTELL}
4472 @end table
4476 @node FSTAT
4477 @section @code{FSTAT} --- Get file status
4478 @fnindex FSTAT
4479 @cindex file system, file status
4481 @table @asis
4482 @item @emph{Description}:
4483 @code{FSTAT} is identical to @ref{STAT}, except that information about an 
4484 already opened file is obtained.
4486 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4488 This intrinsic is provided in both subroutine and function forms; however,
4489 only one form can be used in any given program unit.
4491 @item @emph{Standard}:
4492 GNU extension
4494 @item @emph{Class}:
4495 Subroutine, function
4497 @item @emph{Syntax}:
4498 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4500 @item @emph{Arguments}:
4501 @multitable @columnfractions .15 .70
4502 @item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
4503 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4504 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 
4505                         on success and a system specific error code otherwise.
4506 @end multitable
4508 @item @emph{Example}:
4509 See @ref{STAT} for an example.
4511 @item @emph{See also}:
4512 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4513 @end table
4517 @node FTELL
4518 @section @code{FTELL} --- Current stream position
4519 @fnindex FTELL
4520 @cindex file operation, position
4522 @table @asis
4523 @item @emph{Description}:
4524 Retrieves the current position within an open file.
4526 This intrinsic is provided in both subroutine and function forms; however,
4527 only one form can be used in any given program unit.
4529 @item @emph{Standard}:
4530 GNU extension
4532 @item @emph{Class}:
4533 Subroutine, function
4535 @item @emph{Syntax}:
4536 @multitable @columnfractions .80
4537 @item @code{CALL FTELL(UNIT, OFFSET)}
4538 @item @code{OFFSET = FTELL(UNIT)}
4539 @end multitable
4541 @item @emph{Arguments}:
4542 @multitable @columnfractions .15 .70
4543 @item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
4544 @item @var{UNIT}    @tab Shall of type @code{INTEGER}.
4545 @end multitable
4547 @item @emph{Return value}:
4548 In either syntax, @var{OFFSET} is set to the current offset of unit
4549 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4551 @item @emph{Example}:
4552 @smallexample
4553 PROGRAM test_ftell
4554   INTEGER :: i
4555   OPEN(10, FILE="temp.dat")
4556   CALL ftell(10,i)
4557   WRITE(*,*) i
4558 END PROGRAM
4559 @end smallexample
4561 @item @emph{See also}:
4562 @ref{FSEEK}
4563 @end table
4567 @node GAMMA
4568 @section @code{GAMMA} --- Gamma function
4569 @fnindex GAMMA
4570 @fnindex DGAMMA
4571 @cindex Gamma function
4572 @cindex Factorial function
4574 @table @asis
4575 @item @emph{Description}:
4576 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4577 integer values of @var{X} the Gamma function simplifies to the factorial
4578 function @math{\Gamma(x)=(x-1)!}.
4580 @tex
4582 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4584 @end tex
4586 @item @emph{Standard}:
4587 Fortran 2008 and later
4589 @item @emph{Class}:
4590 Elemental function
4592 @item @emph{Syntax}:
4593 @code{X = GAMMA(X)}
4595 @item @emph{Arguments}:
4596 @multitable @columnfractions .15 .70
4597 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4598 nor a negative integer.
4599 @end multitable
4601 @item @emph{Return value}:
4602 The return value is of type @code{REAL} of the same kind as @var{X}.
4604 @item @emph{Example}:
4605 @smallexample
4606 program test_gamma
4607   real :: x = 1.0
4608   x = gamma(x) ! returns 1.0
4609 end program test_gamma
4610 @end smallexample
4612 @item @emph{Specific names}:
4613 @multitable @columnfractions .20 .20 .20 .25
4614 @item Name             @tab Argument         @tab Return type       @tab Standard
4615 @item @code{GAMMA(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
4616 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
4617 @end multitable
4619 @item @emph{See also}:
4620 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4622 @end table
4626 @node GERROR
4627 @section @code{GERROR} --- Get last system error message
4628 @fnindex GERROR
4629 @cindex system, error handling
4631 @table @asis
4632 @item @emph{Description}:
4633 Returns the system error message corresponding to the last system error.
4634 This resembles the functionality of @code{strerror(3)} in C.
4636 @item @emph{Standard}:
4637 GNU extension
4639 @item @emph{Class}:
4640 Subroutine
4642 @item @emph{Syntax}:
4643 @code{CALL GERROR(RESULT)}
4645 @item @emph{Arguments}:
4646 @multitable @columnfractions .15 .70
4647 @item @var{RESULT}  @tab Shall of type @code{CHARACTER(*)}.
4648 @end multitable
4650 @item @emph{Example}:
4651 @smallexample
4652 PROGRAM test_gerror
4653   CHARACTER(len=100) :: msg
4654   CALL gerror(msg)
4655   WRITE(*,*) msg
4656 END PROGRAM
4657 @end smallexample
4659 @item @emph{See also}:
4660 @ref{IERRNO}, @ref{PERROR}
4661 @end table
4665 @node GETARG
4666 @section @code{GETARG} --- Get command line arguments
4667 @fnindex GETARG
4668 @cindex command-line arguments
4669 @cindex arguments, to program
4671 @table @asis
4672 @item @emph{Description}:
4673 Retrieve the @var{N}th argument that was passed on the
4674 command line when the containing program was invoked.
4676 This intrinsic routine is provided for backwards compatibility with 
4677 GNU Fortran 77.  In new code, programmers should consider the use of 
4678 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 
4679 standard.
4681 @item @emph{Standard}:
4682 GNU extension
4684 @item @emph{Class}:
4685 Subroutine
4687 @item @emph{Syntax}:
4688 @code{CALL GETARG(POS, VALUE)}
4690 @item @emph{Arguments}:
4691 @multitable @columnfractions .15 .70
4692 @item @var{POS}   @tab Shall be of type @code{INTEGER} and not wider than
4693 the default integer kind; @math{@var{POS} \geq 0}
4694 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}. 
4695 @end multitable
4697 @item @emph{Return value}:
4698 After @code{GETARG} returns, the @var{VALUE} argument holds the
4699 @var{POS}th command line argument. If @var{VALUE} can not hold the
4700 argument, it is truncated to fit the length of @var{VALUE}. If there are
4701 less than @var{POS} arguments specified at the command line, @var{VALUE}
4702 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4703 to the name of the program (on systems that support this feature).
4705 @item @emph{Example}:
4706 @smallexample
4707 PROGRAM test_getarg
4708   INTEGER :: i
4709   CHARACTER(len=32) :: arg
4711   DO i = 1, iargc()
4712     CALL getarg(i, arg)
4713     WRITE (*,*) arg
4714   END DO
4715 END PROGRAM
4716 @end smallexample
4718 @item @emph{See also}:
4719 GNU Fortran 77 compatibility function: @ref{IARGC}
4721 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4722 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4723 @end table
4727 @node GET_COMMAND
4728 @section @code{GET_COMMAND} --- Get the entire command line
4729 @fnindex GET_COMMAND
4730 @cindex command-line arguments
4731 @cindex arguments, to program
4733 @table @asis
4734 @item @emph{Description}:
4735 Retrieve the entire command line that was used to invoke the program.
4737 @item @emph{Standard}:
4738 Fortran 2003 and later
4740 @item @emph{Class}:
4741 Subroutine
4743 @item @emph{Syntax}:
4744 @code{CALL GET_COMMAND(CMD)}
4746 @item @emph{Arguments}:
4747 @multitable @columnfractions .15 .70
4748 @item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}. 
4749 @end multitable
4751 @item @emph{Return value}:
4752 Stores the entire command line that was used to invoke the program in @var{ARG}. 
4753 If @var{ARG} is not large enough, the command will be truncated. 
4755 @item @emph{Example}:
4756 @smallexample
4757 PROGRAM test_get_command
4758   CHARACTER(len=255) :: cmd
4759   CALL get_command(cmd)
4760   WRITE (*,*) TRIM(cmd)
4761 END PROGRAM
4762 @end smallexample
4764 @item @emph{See also}:
4765 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4766 @end table
4770 @node GET_COMMAND_ARGUMENT
4771 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4772 @fnindex GET_COMMAND_ARGUMENT
4773 @cindex command-line arguments
4774 @cindex arguments, to program
4776 @table @asis
4777 @item @emph{Description}:
4778 Retrieve the @var{N}th argument that was passed on the
4779 command line when the containing program was invoked.
4781 @item @emph{Standard}:
4782 Fortran 2003 and later
4784 @item @emph{Class}:
4785 Subroutine
4787 @item @emph{Syntax}:
4788 @code{CALL GET_COMMAND_ARGUMENT(N, ARG)}
4790 @item @emph{Arguments}:
4791 @multitable @columnfractions .15 .70
4792 @item @var{N}   @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4793 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}. 
4794 @end multitable
4796 @item @emph{Return value}:
4797 After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the 
4798 @var{N}th command line argument. If @var{ARG} can not hold the argument, it is 
4799 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4800 arguments specified at the command line, @var{ARG} will be filled with blanks. 
4801 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4802 that support this feature).
4804 @item @emph{Example}:
4805 @smallexample
4806 PROGRAM test_get_command_argument
4807   INTEGER :: i
4808   CHARACTER(len=32) :: arg
4810   i = 0
4811   DO
4812     CALL get_command_argument(i, arg)
4813     IF (LEN_TRIM(arg) == 0) EXIT
4815     WRITE (*,*) TRIM(arg)
4816     i = i+1
4817   END DO
4818 END PROGRAM
4819 @end smallexample
4821 @item @emph{See also}:
4822 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4823 @end table
4827 @node GETCWD
4828 @section @code{GETCWD} --- Get current working directory
4829 @fnindex GETCWD
4830 @cindex system, working directory
4832 @table @asis
4833 @item @emph{Description}:
4834 Get current working directory.
4836 This intrinsic is provided in both subroutine and function forms; however,
4837 only one form can be used in any given program unit.
4839 @item @emph{Standard}:
4840 GNU extension
4842 @item @emph{Class}:
4843 Subroutine, function
4845 @item @emph{Syntax}:
4846 @code{CALL GETCWD(CWD [, STATUS])}
4848 @item @emph{Arguments}:
4849 @multitable @columnfractions .15 .70
4850 @item @var{CWD}    @tab The type shall be @code{CHARACTER(*)}.
4851 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, 
4852                         a system specific and nonzero error code otherwise.
4853 @end multitable
4855 @item @emph{Example}:
4856 @smallexample
4857 PROGRAM test_getcwd
4858   CHARACTER(len=255) :: cwd
4859   CALL getcwd(cwd)
4860   WRITE(*,*) TRIM(cwd)
4861 END PROGRAM
4862 @end smallexample
4864 @item @emph{See also}:
4865 @ref{CHDIR}
4866 @end table
4870 @node GETENV
4871 @section @code{GETENV} --- Get an environmental variable
4872 @fnindex GETENV
4873 @cindex environment variable
4875 @table @asis
4876 @item @emph{Description}:
4877 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4879 This intrinsic routine is provided for backwards compatibility with 
4880 GNU Fortran 77.  In new code, programmers should consider the use of 
4881 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4882 2003 standard.
4884 @item @emph{Standard}:
4885 GNU extension
4887 @item @emph{Class}:
4888 Subroutine
4890 @item @emph{Syntax}:
4891 @code{CALL GETENV(ENVVAR, VALUE)}
4893 @item @emph{Arguments}:
4894 @multitable @columnfractions .15 .70
4895 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}. 
4896 @item @var{VALUE}  @tab Shall be of type @code{CHARACTER(*)}. 
4897 @end multitable
4899 @item @emph{Return value}:
4900 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is 
4901 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4902 is not set, @var{VALUE} will be filled with blanks.
4904 @item @emph{Example}:
4905 @smallexample
4906 PROGRAM test_getenv
4907   CHARACTER(len=255) :: homedir
4908   CALL getenv("HOME", homedir)
4909   WRITE (*,*) TRIM(homedir)
4910 END PROGRAM
4911 @end smallexample
4913 @item @emph{See also}:
4914 @ref{GET_ENVIRONMENT_VARIABLE}
4915 @end table
4919 @node GET_ENVIRONMENT_VARIABLE
4920 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4921 @fnindex GET_ENVIRONMENT_VARIABLE
4922 @cindex environment variable
4924 @table @asis
4925 @item @emph{Description}:
4926 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4928 @item @emph{Standard}:
4929 Fortran 2003 and later
4931 @item @emph{Class}:
4932 Subroutine
4934 @item @emph{Syntax}:
4935 @code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}
4937 @item @emph{Arguments}:
4938 @multitable @columnfractions .15 .70
4939 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}. 
4940 @item @var{VALUE}  @tab Shall be of type @code{CHARACTER(*)}. 
4941 @end multitable
4943 @item @emph{Return value}:
4944 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is 
4945 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4946 is not set, @var{VALUE} will be filled with blanks.
4948 @item @emph{Example}:
4949 @smallexample
4950 PROGRAM test_getenv
4951   CHARACTER(len=255) :: homedir
4952   CALL get_environment_variable("HOME", homedir)
4953   WRITE (*,*) TRIM(homedir)
4954 END PROGRAM
4955 @end smallexample
4956 @end table
4960 @node GETGID
4961 @section @code{GETGID} --- Group ID function
4962 @fnindex GETGID
4963 @cindex system, group id
4965 @table @asis
4966 @item @emph{Description}:
4967 Returns the numerical group ID of the current process.
4969 @item @emph{Standard}:
4970 GNU extension
4972 @item @emph{Class}:
4973 Function
4975 @item @emph{Syntax}:
4976 @code{RESULT = GETGID()}
4978 @item @emph{Return value}:
4979 The return value of @code{GETGID} is an @code{INTEGER} of the default
4980 kind.
4983 @item @emph{Example}:
4984 See @code{GETPID} for an example.
4986 @item @emph{See also}:
4987 @ref{GETPID}, @ref{GETUID}
4988 @end table
4992 @node GETLOG
4993 @section @code{GETLOG} --- Get login name
4994 @fnindex GETLOG
4995 @cindex system, login name
4996 @cindex login name
4998 @table @asis
4999 @item @emph{Description}:
5000 Gets the username under which the program is running.
5002 @item @emph{Standard}:
5003 GNU extension
5005 @item @emph{Class}:
5006 Subroutine
5008 @item @emph{Syntax}:
5009 @code{CALL GETLOG(LOGIN)}
5011 @item @emph{Arguments}:
5012 @multitable @columnfractions .15 .70
5013 @item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
5014 @end multitable
5016 @item @emph{Return value}:
5017 Stores the current user name in @var{LOGIN}.  (On systems where POSIX
5018 functions @code{geteuid} and @code{getpwuid} are not available, and 
5019 the @code{getlogin} function is not implemented either, this will
5020 return a blank string.)
5022 @item @emph{Example}:
5023 @smallexample
5024 PROGRAM TEST_GETLOG
5025   CHARACTER(32) :: login
5026   CALL GETLOG(login)
5027   WRITE(*,*) login
5028 END PROGRAM
5029 @end smallexample
5031 @item @emph{See also}:
5032 @ref{GETUID}
5033 @end table
5037 @node GETPID
5038 @section @code{GETPID} --- Process ID function
5039 @fnindex GETPID
5040 @cindex system, process id
5041 @cindex process id
5043 @table @asis
5044 @item @emph{Description}:
5045 Returns the numerical process identifier of the current process.
5047 @item @emph{Standard}:
5048 GNU extension
5050 @item @emph{Class}:
5051 Function
5053 @item @emph{Syntax}:
5054 @code{RESULT = GETPID()}
5056 @item @emph{Return value}:
5057 The return value of @code{GETPID} is an @code{INTEGER} of the default
5058 kind.
5061 @item @emph{Example}:
5062 @smallexample
5063 program info
5064   print *, "The current process ID is ", getpid()
5065   print *, "Your numerical user ID is ", getuid()
5066   print *, "Your numerical group ID is ", getgid()
5067 end program info
5068 @end smallexample
5070 @item @emph{See also}:
5071 @ref{GETGID}, @ref{GETUID}
5072 @end table
5076 @node GETUID
5077 @section @code{GETUID} --- User ID function
5078 @fnindex GETUID
5079 @cindex system, user id
5080 @cindex user id
5082 @table @asis
5083 @item @emph{Description}:
5084 Returns the numerical user ID of the current process.
5086 @item @emph{Standard}:
5087 GNU extension
5089 @item @emph{Class}:
5090 Function
5092 @item @emph{Syntax}:
5093 @code{RESULT = GETUID()}
5095 @item @emph{Return value}:
5096 The return value of @code{GETUID} is an @code{INTEGER} of the default
5097 kind.
5100 @item @emph{Example}:
5101 See @code{GETPID} for an example.
5103 @item @emph{See also}:
5104 @ref{GETPID}, @ref{GETLOG}
5105 @end table
5109 @node GMTIME
5110 @section @code{GMTIME} --- Convert time to GMT info
5111 @fnindex GMTIME
5112 @cindex time, conversion to GMT info
5114 @table @asis
5115 @item @emph{Description}:
5116 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
5117 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
5118 to the UTC time zone (Universal Coordinated Time, also known in some
5119 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5121 @item @emph{Standard}:
5122 GNU extension
5124 @item @emph{Class}:
5125 Subroutine
5127 @item @emph{Syntax}:
5128 @code{CALL GMTIME(STIME, TARRAY)}
5130 @item @emph{Arguments}:
5131 @multitable @columnfractions .15 .70
5132 @item @var{STIME}  @tab An @code{INTEGER(*)} scalar expression
5133                         corresponding to a system time, with 
5134                         @code{INTENT(IN)}.
5135 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
5136                         with @code{INTENT(OUT)}.
5137 @end multitable
5139 @item @emph{Return value}:
5140 The elements of @var{TARRAY} are assigned as follows:
5141 @enumerate
5142 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5143       seconds
5144 @item Minutes after the hour, range 0--59
5145 @item Hours past midnight, range 0--23
5146 @item Day of month, range 0--31
5147 @item Number of months since January, range 0--12
5148 @item Years since 1900
5149 @item Number of days since Sunday, range 0--6
5150 @item Days since January 1
5151 @item Daylight savings indicator: positive if daylight savings is in
5152       effect, zero if not, and negative if the information is not
5153       available.
5154 @end enumerate
5156 @item @emph{See also}:
5157 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5159 @end table
5163 @node HOSTNM
5164 @section @code{HOSTNM} --- Get system host name
5165 @fnindex HOSTNM
5166 @cindex system, host name
5168 @table @asis
5169 @item @emph{Description}:
5170 Retrieves the host name of the system on which the program is running.
5172 This intrinsic is provided in both subroutine and function forms; however,
5173 only one form can be used in any given program unit.
5175 @item @emph{Standard}:
5176 GNU extension
5178 @item @emph{Class}:
5179 Subroutine, function
5181 @item @emph{Syntax}:
5182 @multitable @columnfractions .80
5183 @item @code{CALL HOSTNM(NAME[, STATUS])}
5184 @item @code{STATUS = HOSTNM(NAME)}
5185 @end multitable
5187 @item @emph{Arguments}:
5188 @multitable @columnfractions .15 .70
5189 @item @var{NAME}    @tab Shall of type @code{CHARACTER(*)}.
5190 @item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
5191                          Returns 0 on success, or a system specific error
5192                          code otherwise.
5193 @end multitable
5195 @item @emph{Return value}:
5196 In either syntax, @var{NAME} is set to the current hostname if it can
5197 be obtained, or to a blank string otherwise.
5199 @end table
5203 @node HUGE
5204 @section @code{HUGE} --- Largest number of a kind
5205 @fnindex HUGE
5206 @cindex limits, largest number
5207 @cindex model representation, largest number
5209 @table @asis
5210 @item @emph{Description}:
5211 @code{HUGE(X)} returns the largest number that is not an infinity in
5212 the model of the type of @code{X}.
5214 @item @emph{Standard}:
5215 Fortran 95 and later
5217 @item @emph{Class}:
5218 Inquiry function
5220 @item @emph{Syntax}:
5221 @code{RESULT = HUGE(X)}
5223 @item @emph{Arguments}:
5224 @multitable @columnfractions .15 .70
5225 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5226 @end multitable
5228 @item @emph{Return value}:
5229 The return value is of the same type and kind as @var{X}
5231 @item @emph{Example}:
5232 @smallexample
5233 program test_huge_tiny
5234   print *, huge(0), huge(0.0), huge(0.0d0)
5235   print *, tiny(0.0), tiny(0.0d0)
5236 end program test_huge_tiny
5237 @end smallexample
5238 @end table
5242 @node HYPOT
5243 @section @code{HYPOT} --- Euclidean distance function
5244 @fnindex HYPOT
5245 @cindex Euclidean distance
5247 @table @asis
5248 @item @emph{Description}:
5249 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5250 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5252 @item @emph{Standard}:
5253 Fortran 2008 and later
5255 @item @emph{Class}:
5256 Elemental function
5258 @item @emph{Syntax}:
5259 @code{RESULT = HYPOT(X,Y)}
5261 @item @emph{Arguments}:
5262 @multitable @columnfractions .15 .70
5263 @item @var{X} @tab The type shall be @code{REAL}.
5264 @item @var{Y} @tab The type and kind type parameter shall be the same as
5265 @var{X}.
5266 @end multitable
5268 @item @emph{Return value}:
5269 The return value has the same type and kind type parameter as @var{X}.
5271 @item @emph{Example}:
5272 @smallexample
5273 program test_hypot
5274   real(4) :: x = 1.e0_4, y = 0.5e0_4
5275   x = hypot(x,y)
5276 end program test_hypot
5277 @end smallexample
5278 @end table
5282 @node IACHAR
5283 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence 
5284 @fnindex IACHAR
5285 @cindex @acronym{ASCII} collating sequence
5286 @cindex collating sequence, @acronym{ASCII}
5287 @cindex conversion, to integer
5289 @table @asis
5290 @item @emph{Description}:
5291 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5292 in the first character position of @code{C}.
5294 @item @emph{Standard}:
5295 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5297 @item @emph{Class}:
5298 Elemental function
5300 @item @emph{Syntax}:
5301 @code{RESULT = IACHAR(C [, KIND])}
5303 @item @emph{Arguments}:
5304 @multitable @columnfractions .15 .70
5305 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5306 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5307                       expression indicating the kind parameter of
5308                       the result.
5309 @end multitable
5311 @item @emph{Return value}:
5312 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5313 @var{KIND} is absent, the return value is of default integer kind.
5315 @item @emph{Example}:
5316 @smallexample
5317 program test_iachar
5318   integer i
5319   i = iachar(' ')
5320 end program test_iachar
5321 @end smallexample
5323 @item @emph{Note}:
5324 See @ref{ICHAR} for a discussion of converting between numerical values
5325 and formatted string representations.
5327 @item @emph{See also}:
5328 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5330 @end table
5334 @node IAND
5335 @section @code{IAND} --- Bitwise logical and
5336 @fnindex IAND
5337 @cindex bitwise logical and
5338 @cindex logical and, bitwise
5340 @table @asis
5341 @item @emph{Description}:
5342 Bitwise logical @code{AND}.
5344 @item @emph{Standard}:
5345 Fortran 95 and later
5347 @item @emph{Class}:
5348 Elemental function
5350 @item @emph{Syntax}:
5351 @code{RESULT = IAND(I, J)}
5353 @item @emph{Arguments}:
5354 @multitable @columnfractions .15 .70
5355 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5356 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5357 kind as @var{I}.  (As a GNU extension, different kinds are also 
5358 permitted.)
5359 @end multitable
5361 @item @emph{Return value}:
5362 The return type is @code{INTEGER(*)}, of the same kind as the
5363 arguments.  (If the argument kinds differ, it is of the same kind as
5364 the larger argument.)
5366 @item @emph{Example}:
5367 @smallexample
5368 PROGRAM test_iand
5369   INTEGER :: a, b
5370   DATA a / Z'F' /, b / Z'3' /
5371   WRITE (*,*) IAND(a, b)
5372 END PROGRAM
5373 @end smallexample
5375 @item @emph{See also}:
5376 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5378 @end table
5382 @node IARGC
5383 @section @code{IARGC} --- Get the number of command line arguments
5384 @fnindex IARGC
5385 @cindex command-line arguments
5386 @cindex command-line arguments, number of
5387 @cindex arguments, to program
5389 @table @asis
5390 @item @emph{Description}:
5391 @code{IARGC()} returns the number of arguments passed on the
5392 command line when the containing program was invoked.
5394 This intrinsic routine is provided for backwards compatibility with 
5395 GNU Fortran 77.  In new code, programmers should consider the use of 
5396 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 
5397 standard.
5399 @item @emph{Standard}:
5400 GNU extension
5402 @item @emph{Class}:
5403 Function
5405 @item @emph{Syntax}:
5406 @code{RESULT = IARGC()}
5408 @item @emph{Arguments}:
5409 None.
5411 @item @emph{Return value}:
5412 The number of command line arguments, type @code{INTEGER(4)}.
5414 @item @emph{Example}:
5415 See @ref{GETARG}
5417 @item @emph{See also}:
5418 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5420 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5421 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5422 @end table
5426 @node IBCLR
5427 @section @code{IBCLR} --- Clear bit
5428 @fnindex IBCLR
5429 @cindex bits, unset
5430 @cindex bits, clear
5432 @table @asis
5433 @item @emph{Description}:
5434 @code{IBCLR} returns the value of @var{I} with the bit at position
5435 @var{POS} set to zero.
5437 @item @emph{Standard}:
5438 Fortran 95 and later
5440 @item @emph{Class}:
5441 Elemental function
5443 @item @emph{Syntax}:
5444 @code{RESULT = IBCLR(I, POS)}
5446 @item @emph{Arguments}:
5447 @multitable @columnfractions .15 .70
5448 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5449 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5450 @end multitable
5452 @item @emph{Return value}:
5453 The return value is of type @code{INTEGER(*)} and of the same kind as
5454 @var{I}.
5456 @item @emph{See also}:
5457 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5459 @end table
5463 @node IBITS
5464 @section @code{IBITS} --- Bit extraction
5465 @fnindex IBITS
5466 @cindex bits, get
5467 @cindex bits, extract
5469 @table @asis
5470 @item @emph{Description}:
5471 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5472 starting from bit position @var{POS} and extending left for @var{LEN}
5473 bits.  The result is right-justified and the remaining bits are
5474 zeroed.  The value of @code{POS+LEN} must be less than or equal to the
5475 value @code{BIT_SIZE(I)}.
5477 @item @emph{Standard}:
5478 Fortran 95 and later
5480 @item @emph{Class}:
5481 Elemental function
5483 @item @emph{Syntax}:
5484 @code{RESULT = IBITS(I, POS, LEN)}
5486 @item @emph{Arguments}:
5487 @multitable @columnfractions .15 .70
5488 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5489 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5490 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
5491 @end multitable
5493 @item @emph{Return value}:
5494 The return value is of type @code{INTEGER(*)} and of the same kind as
5495 @var{I}.
5497 @item @emph{See also}:
5498 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5499 @end table
5503 @node IBSET
5504 @section @code{IBSET} --- Set bit
5505 @fnindex IBSET
5506 @cindex bits, set
5508 @table @asis
5509 @item @emph{Description}:
5510 @code{IBSET} returns the value of @var{I} with the bit at position
5511 @var{POS} set to one.
5513 @item @emph{Standard}:
5514 Fortran 95 and later
5516 @item @emph{Class}:
5517 Elemental function
5519 @item @emph{Syntax}:
5520 @code{RESULT = IBSET(I, POS)}
5522 @item @emph{Arguments}:
5523 @multitable @columnfractions .15 .70
5524 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5525 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5526 @end multitable
5528 @item @emph{Return value}:
5529 The return value is of type @code{INTEGER(*)} and of the same kind as
5530 @var{I}.
5532 @item @emph{See also}:
5533 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5535 @end table
5539 @node ICHAR
5540 @section @code{ICHAR} --- Character-to-integer conversion function
5541 @fnindex ICHAR
5542 @cindex conversion, to integer
5544 @table @asis
5545 @item @emph{Description}:
5546 @code{ICHAR(C)} returns the code for the character in the first character
5547 position of @code{C} in the system's native character set.
5548 The correspondence between characters and their codes is not necessarily
5549 the same across different GNU Fortran implementations.
5551 @item @emph{Standard}:
5552 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5554 @item @emph{Class}:
5555 Elemental function
5557 @item @emph{Syntax}:
5558 @code{RESULT = ICHAR(C [, KIND])}
5560 @item @emph{Arguments}:
5561 @multitable @columnfractions .15 .70
5562 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5563 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5564                       expression indicating the kind parameter of
5565                       the result.
5566 @end multitable
5568 @item @emph{Return value}:
5569 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5570 @var{KIND} is absent, the return value is of default integer kind.
5572 @item @emph{Example}:
5573 @smallexample
5574 program test_ichar
5575   integer i
5576   i = ichar(' ')
5577 end program test_ichar
5578 @end smallexample
5580 @item @emph{Note}:
5581 No intrinsic exists to convert between a numeric value and a formatted
5582 character string representation -- for instance, given the
5583 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5584 @code{REAL} value with the value 154, or vice versa. Instead, this
5585 functionality is provided by internal-file I/O, as in the following
5586 example:
5587 @smallexample
5588 program read_val
5589   integer value
5590   character(len=10) string, string2
5591   string = '154'
5592   
5593   ! Convert a string to a numeric value
5594   read (string,'(I10)') value
5595   print *, value
5596   
5597   ! Convert a value to a formatted string
5598   write (string2,'(I10)') value
5599   print *, string2
5600 end program read_val
5601 @end smallexample
5603 @item @emph{See also}:
5604 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5606 @end table
5610 @node IDATE
5611 @section @code{IDATE} --- Get current local time subroutine (day/month/year) 
5612 @fnindex IDATE
5613 @cindex date, current
5614 @cindex current date
5616 @table @asis
5617 @item @emph{Description}:
5618 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the  
5619 current local time. The day (in the range 1-31), month (in the range 1-12), 
5620 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively. 
5621 The year has four significant digits.
5623 @item @emph{Standard}:
5624 GNU extension
5626 @item @emph{Class}:
5627 Subroutine
5629 @item @emph{Syntax}:
5630 @code{CALL IDATE(TARRAY)}
5632 @item @emph{Arguments}:
5633 @multitable @columnfractions .15 .70
5634 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5635 the kind shall be the default integer kind.
5636 @end multitable
5638 @item @emph{Return value}:
5639 Does not return.
5641 @item @emph{Example}:
5642 @smallexample
5643 program test_idate
5644   integer, dimension(3) :: tarray
5645   call idate(tarray)
5646   print *, tarray(1)
5647   print *, tarray(2)
5648   print *, tarray(3)
5649 end program test_idate
5650 @end smallexample
5651 @end table
5655 @node IEOR
5656 @section @code{IEOR} --- Bitwise logical exclusive or
5657 @fnindex IEOR
5658 @cindex bitwise logical exclusive or
5659 @cindex logical exclusive or, bitwise
5661 @table @asis
5662 @item @emph{Description}:
5663 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5664 @var{J}.
5666 @item @emph{Standard}:
5667 Fortran 95 and later
5669 @item @emph{Class}:
5670 Elemental function
5672 @item @emph{Syntax}:
5673 @code{RESULT = IEOR(I, J)}
5675 @item @emph{Arguments}:
5676 @multitable @columnfractions .15 .70
5677 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5678 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5679 kind as @var{I}.  (As a GNU extension, different kinds are also 
5680 permitted.)
5681 @end multitable
5683 @item @emph{Return value}:
5684 The return type is @code{INTEGER(*)}, of the same kind as the
5685 arguments.  (If the argument kinds differ, it is of the same kind as
5686 the larger argument.)
5688 @item @emph{See also}:
5689 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5690 @end table
5694 @node IERRNO
5695 @section @code{IERRNO} --- Get the last system error number
5696 @fnindex IERRNO
5697 @cindex system, error handling
5699 @table @asis
5700 @item @emph{Description}:
5701 Returns the last system error number, as given by the C @code{errno()}
5702 function.
5704 @item @emph{Standard}:
5705 GNU extension
5707 @item @emph{Class}:
5708 Function
5710 @item @emph{Syntax}:
5711 @code{RESULT = IERRNO()}
5713 @item @emph{Arguments}:
5714 None.
5716 @item @emph{Return value}:
5717 The return value is of type @code{INTEGER} and of the default integer
5718 kind.
5720 @item @emph{See also}:
5721 @ref{PERROR}
5722 @end table
5726 @node INDEX intrinsic
5727 @section @code{INDEX} --- Position of a substring within a string
5728 @fnindex INDEX
5729 @cindex substring position
5730 @cindex string, find substring
5732 @table @asis
5733 @item @emph{Description}:
5734 Returns the position of the start of the first occurrence of string
5735 @var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
5736 @var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If 
5737 the @var{BACK} argument is present and true, the return value is the
5738 start of the last occurrence rather than the first.
5740 @item @emph{Standard}:
5741 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5743 @item @emph{Class}:
5744 Elemental function
5746 @item @emph{Syntax}:
5747 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5749 @item @emph{Arguments}:
5750 @multitable @columnfractions .15 .70
5751 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5752 @code{INTENT(IN)}
5753 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5754 @code{INTENT(IN)}
5755 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
5756 @code{INTENT(IN)}
5757 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5758                       expression indicating the kind parameter of
5759                       the result.
5760 @end multitable
5762 @item @emph{Return value}:
5763 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5764 @var{KIND} is absent, the return value is of default integer kind.
5766 @item @emph{See also}:
5767 @ref{SCAN}, @ref{VERIFY}
5768 @end table
5772 @node INT
5773 @section @code{INT} --- Convert to integer type
5774 @fnindex INT
5775 @fnindex IFIX
5776 @fnindex IDINT
5777 @cindex conversion, to integer
5779 @table @asis
5780 @item @emph{Description}:
5781 Convert to integer type
5783 @item @emph{Standard}:
5784 Fortran 77 and later
5786 @item @emph{Class}:
5787 Elemental function
5789 @item @emph{Syntax}:
5790 @code{RESULT = INT(A [, KIND))}
5792 @item @emph{Arguments}:
5793 @multitable @columnfractions .15 .70
5794 @item @var{A}    @tab Shall be of type @code{INTEGER(*)},
5795                       @code{REAL(*)}, or @code{COMPLEX(*)}.
5796 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
5797                       expression indicating the kind parameter of
5798                       the result.
5799 @end multitable
5801 @item @emph{Return value}:
5802 These functions return a @code{INTEGER(*)} variable or array under 
5803 the following rules: 
5805 @table @asis
5806 @item (A)
5807 If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A} 
5808 @item (B)
5809 If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}. 
5810 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed 
5811 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5812 @item (C)
5813 If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
5814 @end table
5816 @item @emph{Example}:
5817 @smallexample
5818 program test_int
5819   integer :: i = 42
5820   complex :: z = (-3.7, 1.0)
5821   print *, int(i)
5822   print *, int(z), int(z,8)
5823 end program
5824 @end smallexample
5826 @item @emph{Specific names}:
5827 @multitable @columnfractions .20 .20 .20 .25
5828 @item Name             @tab Argument            @tab Return type       @tab Standard
5829 @item @code{IFIX(A)}   @tab @code{REAL(4) A}    @tab @code{INTEGER}    @tab Fortran 77 and later
5830 @item @code{IDINT(A)}  @tab @code{REAL(8) A}    @tab @code{INTEGER}    @tab Fortran 77 and later
5831 @end multitable
5833 @end table
5837 @node INT2
5838 @section @code{INT2} --- Convert to 16-bit integer type
5839 @fnindex INT2
5840 @fnindex SHORT
5841 @cindex conversion, to integer
5843 @table @asis
5844 @item @emph{Description}:
5845 Convert to a @code{KIND=2} integer type. This is equivalent to the
5846 standard @code{INT} intrinsic with an optional argument of
5847 @code{KIND=2}, and is only included for backwards compatibility.
5849 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5851 @item @emph{Standard}:
5852 GNU extension
5854 @item @emph{Class}:
5855 Elemental function
5857 @item @emph{Syntax}:
5858 @code{RESULT = INT2(A)}
5860 @item @emph{Arguments}:
5861 @multitable @columnfractions .15 .70
5862 @item @var{A}    @tab Shall be of type @code{INTEGER(*)},
5863                       @code{REAL(*)}, or @code{COMPLEX(*)}.
5864 @end multitable
5866 @item @emph{Return value}:
5867 The return value is a @code{INTEGER(2)} variable.
5869 @item @emph{See also}:
5870 @ref{INT}, @ref{INT8}, @ref{LONG}
5871 @end table
5875 @node INT8
5876 @section @code{INT8} --- Convert to 64-bit integer type
5877 @fnindex INT8
5878 @cindex conversion, to integer
5880 @table @asis
5881 @item @emph{Description}:
5882 Convert to a @code{KIND=8} integer type. This is equivalent to the
5883 standard @code{INT} intrinsic with an optional argument of
5884 @code{KIND=8}, and is only included for backwards compatibility.
5886 @item @emph{Standard}:
5887 GNU extension
5889 @item @emph{Class}:
5890 Elemental function
5892 @item @emph{Syntax}:
5893 @code{RESULT = INT8(A)}
5895 @item @emph{Arguments}:
5896 @multitable @columnfractions .15 .70
5897 @item @var{A}    @tab Shall be of type @code{INTEGER(*)},
5898                       @code{REAL(*)}, or @code{COMPLEX(*)}.
5899 @end multitable
5901 @item @emph{Return value}:
5902 The return value is a @code{INTEGER(8)} variable.
5904 @item @emph{See also}:
5905 @ref{INT}, @ref{INT2}, @ref{LONG}
5906 @end table
5910 @node IOR
5911 @section @code{IOR} --- Bitwise logical or
5912 @fnindex IOR
5913 @cindex bitwise logical or
5914 @cindex logical or, bitwise
5916 @table @asis
5917 @item @emph{Description}:
5918 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
5919 @var{J}.
5921 @item @emph{Standard}:
5922 Fortran 95 and later
5924 @item @emph{Class}:
5925 Elemental function
5927 @item @emph{Syntax}:
5928 @code{RESULT = IOR(I, J)}
5930 @item @emph{Arguments}:
5931 @multitable @columnfractions .15 .70
5932 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5933 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5934 kind as @var{I}.  (As a GNU extension, different kinds are also 
5935 permitted.)
5936 @end multitable
5938 @item @emph{Return value}:
5939 The return type is @code{INTEGER(*)}, of the same kind as the
5940 arguments.  (If the argument kinds differ, it is of the same kind as
5941 the larger argument.)
5943 @item @emph{See also}:
5944 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5945 @end table
5949 @node IRAND
5950 @section @code{IRAND} --- Integer pseudo-random number
5951 @fnindex IRAND
5952 @cindex random number generation
5954 @table @asis
5955 @item @emph{Description}:
5956 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
5957 distribution between 0 and a system-dependent limit (which is in most
5958 cases 2147483647). If @var{FLAG} is 0, the next number
5959 in the current sequence is returned; if @var{FLAG} is 1, the generator
5960 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
5961 it is used as a new seed with @code{SRAND}.
5963 This intrinsic routine is provided for backwards compatibility with
5964 GNU Fortran 77. It implements a simple modulo generator as provided 
5965 by @command{g77}. For new code, one should consider the use of 
5966 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
5968 @item @emph{Standard}:
5969 GNU extension
5971 @item @emph{Class}:
5972 Function
5974 @item @emph{Syntax}:
5975 @code{RESULT = IRAND(FLAG)}
5977 @item @emph{Arguments}:
5978 @multitable @columnfractions .15 .70
5979 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
5980 @end multitable
5982 @item @emph{Return value}:
5983 The return value is of @code{INTEGER(kind=4)} type.
5985 @item @emph{Example}:
5986 @smallexample
5987 program test_irand
5988   integer,parameter :: seed = 86456
5989   
5990   call srand(seed)
5991   print *, irand(), irand(), irand(), irand()
5992   print *, irand(seed), irand(), irand(), irand()
5993 end program test_irand
5994 @end smallexample
5996 @end table
6000 @node IS_IOSTAT_END
6001 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6002 @fnindex IS_IOSTAT_END
6003 @cindex IOSTAT, end of file
6005 @table @asis
6006 @item @emph{Description}:
6007 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6008 status ``end of file''. The function is equivalent to comparing the variable
6009 with the @code{IOSTAT_END} parameter of the intrinsic module
6010 @code{ISO_FORTRAN_ENV}.
6012 @item @emph{Standard}:
6013 Fortran 2003 and later
6015 @item @emph{Class}:
6016 Elemental function
6018 @item @emph{Syntax}:
6019 @code{RESULT = IS_IOSTAT_END(I)}
6021 @item @emph{Arguments}:
6022 @multitable @columnfractions .15 .70
6023 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6024 @end multitable
6026 @item @emph{Return value}:
6027 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6028 @var{I} has the value which indicates an end of file condition for
6029 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6031 @item @emph{Example}:
6032 @smallexample
6033 PROGRAM iostat
6034   IMPLICIT NONE
6035   INTEGER :: stat, i
6036   OPEN(88, FILE='test.dat')
6037   READ(88, *, IOSTAT=stat) i
6038   IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6039 END PROGRAM
6040 @end smallexample
6041 @end table
6045 @node IS_IOSTAT_EOR
6046 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6047 @fnindex IS_IOSTAT_EOR
6048 @cindex IOSTAT, end of record
6050 @table @asis
6051 @item @emph{Description}:
6052 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6053 status ``end of record''. The function is equivalent to comparing the
6054 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6055 @code{ISO_FORTRAN_ENV}.
6057 @item @emph{Standard}:
6058 Fortran 2003 and later
6060 @item @emph{Class}:
6061 Elemental function
6063 @item @emph{Syntax}:
6064 @code{RESULT = IS_IOSTAT_EOR(I)}
6066 @item @emph{Arguments}:
6067 @multitable @columnfractions .15 .70
6068 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6069 @end multitable
6071 @item @emph{Return value}:
6072 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6073 @var{I} has the value which indicates an end of file condition for
6074 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6076 @item @emph{Example}:
6077 @smallexample
6078 PROGRAM iostat
6079   IMPLICIT NONE
6080   INTEGER :: stat, i(50)
6081   OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6082   READ(88, IOSTAT=stat) i
6083   IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6084 END PROGRAM
6085 @end smallexample
6086 @end table
6090 @node ISATTY
6091 @section @code{ISATTY} --- Whether a unit is a terminal device.
6092 @fnindex ISATTY
6093 @cindex system, terminal
6095 @table @asis
6096 @item @emph{Description}:
6097 Determine whether a unit is connected to a terminal device.
6099 @item @emph{Standard}:
6100 GNU extension
6102 @item @emph{Class}:
6103 Function
6105 @item @emph{Syntax}:
6106 @code{RESULT = ISATTY(UNIT)}
6108 @item @emph{Arguments}:
6109 @multitable @columnfractions .15 .70
6110 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
6111 @end multitable
6113 @item @emph{Return value}:
6114 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal 
6115 device, @code{.FALSE.} otherwise.
6117 @item @emph{Example}:
6118 @smallexample
6119 PROGRAM test_isatty
6120   INTEGER(kind=1) :: unit
6121   DO unit = 1, 10
6122     write(*,*) isatty(unit=unit)
6123   END DO
6124 END PROGRAM
6125 @end smallexample
6126 @item @emph{See also}:
6127 @ref{TTYNAM}
6128 @end table
6132 @node ISHFT
6133 @section @code{ISHFT} --- Shift bits
6134 @fnindex ISHFT
6135 @cindex bits, shift
6137 @table @asis
6138 @item @emph{Description}:
6139 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6140 bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
6141 zero corresponds to a left shift, a value of zero corresponds to no
6142 shift, and a value less than zero corresponds to a right shift.  If the
6143 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6144 value is undefined.  Bits shifted out from the left end or right end are
6145 lost; zeros are shifted in from the opposite end.
6147 @item @emph{Standard}:
6148 Fortran 95 and later
6150 @item @emph{Class}:
6151 Elemental function
6153 @item @emph{Syntax}:
6154 @code{RESULT = ISHFT(I, SHIFT)}
6156 @item @emph{Arguments}:
6157 @multitable @columnfractions .15 .70
6158 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6159 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6160 @end multitable
6162 @item @emph{Return value}:
6163 The return value is of type @code{INTEGER(*)} and of the same kind as
6164 @var{I}.
6166 @item @emph{See also}:
6167 @ref{ISHFTC}
6168 @end table
6172 @node ISHFTC
6173 @section @code{ISHFTC} --- Shift bits circularly
6174 @fnindex ISHFTC
6175 @cindex bits, shift circular
6177 @table @asis
6178 @item @emph{Description}:
6179 @code{ISHFTC} returns a value corresponding to @var{I} with the
6180 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6181 is, bits shifted out one end are shifted into the opposite end.  A value
6182 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6183 zero corresponds to no shift, and a value less than zero corresponds to
6184 a right shift.  The absolute value of @var{SHIFT} must be less than
6185 @var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
6186 equivalent to @code{BIT_SIZE(I)}.
6188 @item @emph{Standard}:
6189 Fortran 95 and later
6191 @item @emph{Class}:
6192 Elemental function
6194 @item @emph{Syntax}:
6195 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6197 @item @emph{Arguments}:
6198 @multitable @columnfractions .15 .70
6199 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6200 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6201 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
6202 the value must be greater than zero and less than or equal to
6203 @code{BIT_SIZE(I)}.
6204 @end multitable
6206 @item @emph{Return value}:
6207 The return value is of type @code{INTEGER(*)} and of the same kind as
6208 @var{I}.
6210 @item @emph{See also}:
6211 @ref{ISHFT}
6212 @end table
6216 @node ISNAN
6217 @section @code{ISNAN} --- Test for a NaN
6218 @fnindex ISNAN
6219 @cindex IEEE, ISNAN
6221 @table @asis
6222 @item @emph{Description}:
6223 @code{ISNAN} tests whether a floating-point value is an IEEE
6224 Not-a-Number (NaN).
6225 @item @emph{Standard}:
6226 GNU extension
6228 @item @emph{Class}:
6229 Elemental function
6231 @item @emph{Syntax}:
6232 @code{ISNAN(X)}
6234 @item @emph{Arguments}:
6235 @multitable @columnfractions .15 .70
6236 @item @var{X} @tab Variable of the type @code{REAL}.
6238 @end multitable
6240 @item @emph{Return value}:
6241 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6242 if @var{X} is a NaN and @code{FALSE} otherwise.
6244 @item @emph{Example}:
6245 @smallexample
6246 program test_nan
6247   implicit none
6248   real :: x
6249   x = -1.0
6250   x = sqrt(x)
6251   if (isnan(x)) stop '"x" is a NaN'
6252 end program test_nan
6253 @end smallexample
6254 @end table
6258 @node ITIME
6259 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) 
6260 @fnindex ITIME
6261 @cindex time, current
6262 @cindex current time
6264 @table @asis
6265 @item @emph{Description}:
6266 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the  
6267 current local time. The hour (in the range 1-24), minute (in the range 1-60), 
6268 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY}, 
6269 respectively.
6271 @item @emph{Standard}:
6272 GNU extension
6274 @item @emph{Class}:
6275 Subroutine
6277 @item @emph{Syntax}:
6278 @code{CALL ITIME(TARRAY)}
6280 @item @emph{Arguments}:
6281 @multitable @columnfractions .15 .70
6282 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6283 and the kind shall be the default integer kind.
6284 @end multitable
6286 @item @emph{Return value}:
6287 Does not return.
6290 @item @emph{Example}:
6291 @smallexample
6292 program test_itime
6293   integer, dimension(3) :: tarray
6294   call itime(tarray)
6295   print *, tarray(1)
6296   print *, tarray(2)
6297   print *, tarray(3)
6298 end program test_itime
6299 @end smallexample
6300 @end table
6304 @node KILL
6305 @section @code{KILL} --- Send a signal to a process
6306 @fnindex KILL
6308 @table @asis
6309 @item @emph{Description}:
6310 @item @emph{Standard}:
6311 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6312 See @code{kill(2)}.
6314 This intrinsic is provided in both subroutine and function forms; however,
6315 only one form can be used in any given program unit.
6317 @item @emph{Class}:
6318 Subroutine, function
6320 @item @emph{Syntax}:
6321 @code{CALL KILL(PID, SIGNAL [, STATUS])}
6323 @item @emph{Arguments}:
6324 @multitable @columnfractions .15 .70
6325 @item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
6326 @code{INTENT(IN)}
6327 @item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
6328 @code{INTENT(IN)}
6329 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6330                         @code{INTEGER(8)}. Returns 0 on success, or a
6331                         system-specific error code otherwise.
6332 @end multitable
6334 @item @emph{See also}:
6335 @ref{ABORT}, @ref{EXIT}
6336 @end table
6340 @node KIND
6341 @section @code{KIND} --- Kind of an entity
6342 @fnindex KIND
6343 @cindex kind
6345 @table @asis
6346 @item @emph{Description}:
6347 @code{KIND(X)} returns the kind value of the entity @var{X}.
6349 @item @emph{Standard}:
6350 Fortran 95 and later
6352 @item @emph{Class}:
6353 Inquiry function
6355 @item @emph{Syntax}:
6356 @code{K = KIND(X)}
6358 @item @emph{Arguments}:
6359 @multitable @columnfractions .15 .70
6360 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6361 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6362 @end multitable
6364 @item @emph{Return value}:
6365 The return value is a scalar of type @code{INTEGER} and of the default
6366 integer kind.
6368 @item @emph{Example}:
6369 @smallexample
6370 program test_kind
6371   integer,parameter :: kc = kind(' ')
6372   integer,parameter :: kl = kind(.true.)
6374   print *, "The default character kind is ", kc
6375   print *, "The default logical kind is ", kl
6376 end program test_kind
6377 @end smallexample
6379 @end table
6383 @node LBOUND
6384 @section @code{LBOUND} --- Lower dimension bounds of an array
6385 @fnindex LBOUND
6386 @cindex array, lower bound
6388 @table @asis
6389 @item @emph{Description}:
6390 Returns the lower bounds of an array, or a single lower bound
6391 along the @var{DIM} dimension.
6392 @item @emph{Standard}:
6393 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6395 @item @emph{Class}:
6396 Inquiry function
6398 @item @emph{Syntax}:
6399 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6401 @item @emph{Arguments}:
6402 @multitable @columnfractions .15 .70
6403 @item @var{ARRAY} @tab Shall be an array, of any type.
6404 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
6405 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6406                       expression indicating the kind parameter of
6407                       the result.
6408 @end multitable
6410 @item @emph{Return value}:
6411 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6412 @var{KIND} is absent, the return value is of default integer kind.
6413 If @var{DIM} is absent, the result is an array of the lower bounds of
6414 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
6415 corresponding to the lower bound of the array along that dimension.  If
6416 @var{ARRAY} is an expression rather than a whole array or array
6417 structure component, or if it has a zero extent along the relevant
6418 dimension, the lower bound is taken to be 1.
6420 @item @emph{See also}:
6421 @ref{UBOUND}
6422 @end table
6426 @node LEN
6427 @section @code{LEN} --- Length of a character entity
6428 @fnindex LEN
6429 @cindex string, length
6431 @table @asis
6432 @item @emph{Description}:
6433 Returns the length of a character string.  If @var{STRING} is an array,
6434 the length of an element of @var{STRING} is returned.  Note that
6435 @var{STRING} need not be defined when this intrinsic is invoked, since
6436 only the length, not the content, of @var{STRING} is needed.
6438 @item @emph{Standard}:
6439 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6441 @item @emph{Class}:
6442 Inquiry function
6444 @item @emph{Syntax}:
6445 @code{L = LEN(STRING [, KIND])}
6447 @item @emph{Arguments}:
6448 @multitable @columnfractions .15 .70
6449 @item @var{STRING} @tab Shall be a scalar or array of type
6450 @code{CHARACTER(*)}, with @code{INTENT(IN)}
6451 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6452                       expression indicating the kind parameter of
6453                       the result.
6454 @end multitable
6456 @item @emph{Return value}:
6457 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6458 @var{KIND} is absent, the return value is of default integer kind.
6460 @item @emph{See also}:
6461 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6462 @end table
6466 @node LEN_TRIM
6467 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6468 @fnindex LEN_TRIM
6469 @cindex string, length, without trailing whitespace
6471 @table @asis
6472 @item @emph{Description}:
6473 Returns the length of a character string, ignoring any trailing blanks.
6475 @item @emph{Standard}:
6476 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6478 @item @emph{Class}:
6479 Elemental function
6481 @item @emph{Syntax}:
6482 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6484 @item @emph{Arguments}:
6485 @multitable @columnfractions .15 .70
6486 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6487 with @code{INTENT(IN)}
6488 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6489                       expression indicating the kind parameter of
6490                       the result.
6491 @end multitable
6493 @item @emph{Return value}:
6494 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6495 @var{KIND} is absent, the return value is of default integer kind.
6497 @item @emph{See also}:
6498 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6499 @end table
6503 @node LOG_GAMMA
6504 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
6505 @fnindex LOG_GAMMA
6506 @fnindex LGAMMA
6507 @fnindex ALGAMA
6508 @fnindex DLGAMA
6509 @cindex Gamma function, logarithm of
6511 @table @asis
6512 @item @emph{Description}:
6513 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
6514 of the Gamma (@math{\Gamma}) function.
6516 @item @emph{Standard}:
6517 Fortran 2008 and later
6519 @item @emph{Class}:
6520 Elemental function
6522 @item @emph{Syntax}:
6523 @code{X = LOG_GAMMA(X)}
6525 @item @emph{Arguments}:
6526 @multitable @columnfractions .15 .70
6527 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6528 nor a negative integer.
6529 @end multitable
6531 @item @emph{Return value}:
6532 The return value is of type @code{REAL} of the same kind as @var{X}.
6534 @item @emph{Example}:
6535 @smallexample
6536 program test_log_gamma
6537   real :: x = 1.0
6538   x = lgamma(x) ! returns 0.0
6539 end program test_log_gamma
6540 @end smallexample
6542 @item @emph{Specific names}:
6543 @multitable @columnfractions .20 .20 .20 .25
6544 @item Name             @tab Argument         @tab Return type       @tab Standard
6545 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
6546 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
6547 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
6548 @end multitable
6550 @item @emph{See also}:
6551 Gamma function: @ref{GAMMA}
6553 @end table
6557 @node LGE
6558 @section @code{LGE} --- Lexical greater than or equal
6559 @fnindex LGE
6560 @cindex lexical comparison of strings
6561 @cindex string, comparison
6563 @table @asis
6564 @item @emph{Description}:
6565 Determines whether one string is lexically greater than or equal to
6566 another string, where the two strings are interpreted as containing
6567 ASCII character codes.  If the String A and String B are not the same
6568 length, the shorter is compared as if spaces were appended to it to form
6569 a value that has the same length as the longer.
6571 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6572 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6573 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6574 that the latter use the processor's character ordering (which is not
6575 ASCII on some targets), whereas the former always use the ASCII
6576 ordering.
6578 @item @emph{Standard}:
6579 Fortran 77 and later
6581 @item @emph{Class}:
6582 Elemental function
6584 @item @emph{Syntax}:
6585 @code{RESULT = LGE(STRING_A, STRING_B)}
6587 @item @emph{Arguments}:
6588 @multitable @columnfractions .15 .70
6589 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6590 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6591 @end multitable
6593 @item @emph{Return value}:
6594 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6595 otherwise, based on the ASCII ordering.
6597 @item @emph{See also}:
6598 @ref{LGT}, @ref{LLE}, @ref{LLT}
6599 @end table
6603 @node LGT
6604 @section @code{LGT} --- Lexical greater than
6605 @fnindex LGT
6606 @cindex lexical comparison of strings
6607 @cindex string, comparison
6609 @table @asis
6610 @item @emph{Description}:
6611 Determines whether one string is lexically greater than another string,
6612 where the two strings are interpreted as containing ASCII character
6613 codes.  If the String A and String B are not the same length, the
6614 shorter is compared as if spaces were appended to it to form a value
6615 that has the same length as the longer.
6617 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6618 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6619 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6620 that the latter use the processor's character ordering (which is not
6621 ASCII on some targets), whereas the former always use the ASCII
6622 ordering.
6624 @item @emph{Standard}:
6625 Fortran 77 and later
6627 @item @emph{Class}:
6628 Elemental function
6630 @item @emph{Syntax}:
6631 @code{RESULT = LGT(STRING_A, STRING_B)}
6633 @item @emph{Arguments}:
6634 @multitable @columnfractions .15 .70
6635 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6636 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6637 @end multitable
6639 @item @emph{Return value}:
6640 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6641 otherwise, based on the ASCII ordering.
6643 @item @emph{See also}:
6644 @ref{LGE}, @ref{LLE}, @ref{LLT}
6645 @end table
6649 @node LINK
6650 @section @code{LINK} --- Create a hard link
6651 @fnindex LINK
6652 @cindex file system, create link
6653 @cindex file system, hard link
6655 @table @asis
6656 @item @emph{Description}:
6657 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6658 character (@code{CHAR(0)}) can be used to mark the end of the names in
6659 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6660 names are ignored.  If the @var{STATUS} argument is supplied, it
6661 contains 0 on success or a nonzero error code upon return; see
6662 @code{link(2)}.
6664 This intrinsic is provided in both subroutine and function forms;
6665 however, only one form can be used in any given program unit.
6667 @item @emph{Standard}:
6668 GNU extension
6670 @item @emph{Class}:
6671 Subroutine, function
6673 @item @emph{Syntax}:
6674 @multitable @columnfractions .80
6675 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6676 @item @code{STATUS = LINK(PATH1, PATH2)}
6677 @end multitable
6679 @item @emph{Arguments}:
6680 @multitable @columnfractions .15 .70
6681 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6682 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6683 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6684 @end multitable
6686 @item @emph{See also}:
6687 @ref{SYMLNK}, @ref{UNLINK}
6688 @end table
6692 @node LLE
6693 @section @code{LLE} --- Lexical less than or equal
6694 @fnindex LLE
6695 @cindex lexical comparison of strings
6696 @cindex string, comparison
6698 @table @asis
6699 @item @emph{Description}:
6700 Determines whether one string is lexically less than or equal to another
6701 string, where the two strings are interpreted as containing ASCII
6702 character codes.  If the String A and String B are not the same length,
6703 the shorter is compared as if spaces were appended to it to form a value
6704 that has the same length as the longer.
6706 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6707 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6708 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6709 that the latter use the processor's character ordering (which is not
6710 ASCII on some targets), whereas the former always use the ASCII
6711 ordering.
6713 @item @emph{Standard}:
6714 Fortran 77 and later
6716 @item @emph{Class}:
6717 Elemental function
6719 @item @emph{Syntax}:
6720 @code{RESULT = LLE(STRING_A, STRING_B)}
6722 @item @emph{Arguments}:
6723 @multitable @columnfractions .15 .70
6724 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6725 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6726 @end multitable
6728 @item @emph{Return value}:
6729 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6730 otherwise, based on the ASCII ordering.
6732 @item @emph{See also}:
6733 @ref{LGE}, @ref{LGT}, @ref{LLT}
6734 @end table
6738 @node LLT
6739 @section @code{LLT} --- Lexical less than
6740 @fnindex LLT
6741 @cindex lexical comparison of strings
6742 @cindex string, comparison
6744 @table @asis
6745 @item @emph{Description}:
6746 Determines whether one string is lexically less than another string,
6747 where the two strings are interpreted as containing ASCII character
6748 codes.  If the String A and String B are not the same length, the
6749 shorter is compared as if spaces were appended to it to form a value
6750 that has the same length as the longer.
6752 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6753 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6754 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6755 that the latter use the processor's character ordering (which is not
6756 ASCII on some targets), whereas the former always use the ASCII
6757 ordering.
6759 @item @emph{Standard}:
6760 Fortran 77 and later
6762 @item @emph{Class}:
6763 Elemental function
6765 @item @emph{Syntax}:
6766 @code{RESULT = LLT(STRING_A, STRING_B)}
6768 @item @emph{Arguments}:
6769 @multitable @columnfractions .15 .70
6770 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6771 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6772 @end multitable
6774 @item @emph{Return value}:
6775 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6776 otherwise, based on the ASCII ordering.
6778 @item @emph{See also}:
6779 @ref{LGE}, @ref{LGT}, @ref{LLE}
6780 @end table
6784 @node LNBLNK
6785 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6786 @fnindex LNBLNK
6787 @cindex string, find non-blank character
6789 @table @asis
6790 @item @emph{Description}:
6791 Returns the length of a character string, ignoring any trailing blanks.
6792 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6793 included for backwards compatibility.
6795 @item @emph{Standard}:
6796 GNU extension
6798 @item @emph{Class}:
6799 Elemental function
6801 @item @emph{Syntax}:
6802 @code{RESULT = LNBLNK(STRING)}
6804 @item @emph{Arguments}:
6805 @multitable @columnfractions .15 .70
6806 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6807 with @code{INTENT(IN)}
6808 @end multitable
6810 @item @emph{Return value}:
6811 The return value is of @code{INTEGER(kind=4)} type.
6813 @item @emph{See also}:
6814 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6815 @end table
6819 @node LOC
6820 @section @code{LOC} --- Returns the address of a variable
6821 @fnindex LOC
6822 @cindex location of a variable in memory
6824 @table @asis
6825 @item @emph{Description}:
6826 @code{LOC(X)} returns the address of @var{X} as an integer.
6828 @item @emph{Standard}:
6829 GNU extension
6831 @item @emph{Class}:
6832 Inquiry function
6834 @item @emph{Syntax}:
6835 @code{RESULT = LOC(X)}
6837 @item @emph{Arguments}:
6838 @multitable @columnfractions .15 .70
6839 @item @var{X} @tab Variable of any type.
6840 @end multitable
6842 @item @emph{Return value}:
6843 The return value is of type @code{INTEGER}, with a @code{KIND}
6844 corresponding to the size (in bytes) of a memory address on the target
6845 machine.
6847 @item @emph{Example}:
6848 @smallexample
6849 program test_loc
6850   integer :: i
6851   real :: r
6852   i = loc(r)
6853   print *, i
6854 end program test_loc
6855 @end smallexample
6856 @end table
6860 @node LOG
6861 @section @code{LOG} --- Logarithm function
6862 @fnindex LOG
6863 @fnindex ALOG
6864 @fnindex DLOG
6865 @fnindex CLOG
6866 @fnindex ZLOG
6867 @fnindex CDLOG
6868 @cindex exponential function, inverse
6869 @cindex logarithmic function
6871 @table @asis
6872 @item @emph{Description}:
6873 @code{LOG(X)} computes the logarithm of @var{X}.
6875 @item @emph{Standard}:
6876 Fortran 77 and later
6878 @item @emph{Class}:
6879 Elemental function
6881 @item @emph{Syntax}:
6882 @code{RESULT = LOG(X)}
6884 @item @emph{Arguments}:
6885 @multitable @columnfractions .15 .70
6886 @item @var{X} @tab The type shall be @code{REAL(*)} or
6887 @code{COMPLEX(*)}.
6888 @end multitable
6890 @item @emph{Return value}:
6891 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6892 The kind type parameter is the same as @var{X}.
6894 @item @emph{Example}:
6895 @smallexample
6896 program test_log
6897   real(8) :: x = 1.0_8
6898   complex :: z = (1.0, 2.0)
6899   x = log(x)
6900   z = log(z)
6901 end program test_log
6902 @end smallexample
6904 @item @emph{Specific names}:
6905 @multitable @columnfractions .20 .20 .20 .25
6906 @item Name            @tab Argument          @tab Return type       @tab Standard
6907 @item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
6908 @item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
6909 @item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
6910 @item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
6911 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
6912 @end multitable
6913 @end table
6917 @node LOG10
6918 @section @code{LOG10} --- Base 10 logarithm function
6919 @fnindex LOG10
6920 @fnindex ALOG10
6921 @fnindex DLOG10
6922 @cindex exponential function, inverse
6923 @cindex logarithmic function
6925 @table @asis
6926 @item @emph{Description}:
6927 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6929 @item @emph{Standard}:
6930 Fortran 77 and later
6932 @item @emph{Class}:
6933 Elemental function
6935 @item @emph{Syntax}:
6936 @code{RESULT = LOG10(X)}
6938 @item @emph{Arguments}:
6939 @multitable @columnfractions .15 .70
6940 @item @var{X} @tab The type shall be @code{REAL(*)}.
6941 @end multitable
6943 @item @emph{Return value}:
6944 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6945 The kind type parameter is the same as @var{X}.
6947 @item @emph{Example}:
6948 @smallexample
6949 program test_log10
6950   real(8) :: x = 10.0_8
6951   x = log10(x)
6952 end program test_log10
6953 @end smallexample
6955 @item @emph{Specific names}:
6956 @multitable @columnfractions .20 .20 .20 .25
6957 @item Name            @tab Argument          @tab Return type       @tab Standard
6958 @item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
6959 @item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
6960 @end multitable
6961 @end table
6965 @node LOGICAL
6966 @section @code{LOGICAL} --- Convert to logical type
6967 @fnindex LOGICAL
6968 @cindex conversion, to logical
6970 @table @asis
6971 @item @emph{Description}:
6972 Converts one kind of @code{LOGICAL} variable to another.
6974 @item @emph{Standard}:
6975 Fortran 95 and later
6977 @item @emph{Class}:
6978 Elemental function
6980 @item @emph{Syntax}:
6981 @code{RESULT = LOGICAL(L [, KIND])}
6983 @item @emph{Arguments}:
6984 @multitable @columnfractions .15 .70
6985 @item @var{L}    @tab The type shall be @code{LOGICAL(*)}.
6986 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
6987                       expression indicating the kind parameter of
6988                       the result.
6989 @end multitable
6991 @item @emph{Return value}:
6992 The return value is a @code{LOGICAL} value equal to @var{L}, with a
6993 kind corresponding to @var{KIND}, or of the default logical kind if
6994 @var{KIND} is not given.
6996 @item @emph{See also}:
6997 @ref{INT}, @ref{REAL}, @ref{CMPLX}
6998 @end table
7002 @node LONG
7003 @section @code{LONG} --- Convert to integer type
7004 @fnindex LONG
7005 @cindex conversion, to integer
7007 @table @asis
7008 @item @emph{Description}:
7009 Convert to a @code{KIND=4} integer type, which is the same size as a C
7010 @code{long} integer.  This is equivalent to the standard @code{INT}
7011 intrinsic with an optional argument of @code{KIND=4}, and is only
7012 included for backwards compatibility.
7014 @item @emph{Standard}:
7015 GNU extension
7017 @item @emph{Class}:
7018 Elemental function
7020 @item @emph{Syntax}:
7021 @code{RESULT = LONG(A)}
7023 @item @emph{Arguments}:
7024 @multitable @columnfractions .15 .70
7025 @item @var{A}    @tab Shall be of type @code{INTEGER(*)},
7026                       @code{REAL(*)}, or @code{COMPLEX(*)}.
7027 @end multitable
7029 @item @emph{Return value}:
7030 The return value is a @code{INTEGER(4)} variable.
7032 @item @emph{See also}:
7033 @ref{INT}, @ref{INT2}, @ref{INT8}
7034 @end table
7038 @node LSHIFT
7039 @section @code{LSHIFT} --- Left shift bits
7040 @fnindex LSHIFT
7041 @cindex bits, shift left
7043 @table @asis
7044 @item @emph{Description}:
7045 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7046 bits shifted left by @var{SHIFT} places.  If the absolute value of
7047 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 
7048 Bits shifted out from the left end are lost; zeros are shifted in from
7049 the opposite end.
7051 This function has been superseded by the @code{ISHFT} intrinsic, which
7052 is standard in Fortran 95 and later.
7054 @item @emph{Standard}:
7055 GNU extension
7057 @item @emph{Class}:
7058 Elemental function
7060 @item @emph{Syntax}:
7061 @code{RESULT = LSHIFT(I, SHIFT)}
7063 @item @emph{Arguments}:
7064 @multitable @columnfractions .15 .70
7065 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
7066 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
7067 @end multitable
7069 @item @emph{Return value}:
7070 The return value is of type @code{INTEGER(*)} and of the same kind as
7071 @var{I}.
7073 @item @emph{See also}:
7074 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7076 @end table
7080 @node LSTAT
7081 @section @code{LSTAT} --- Get file status
7082 @fnindex LSTAT
7083 @cindex file system, file status
7085 @table @asis
7086 @item @emph{Description}:
7087 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link, 
7088 then the link itself is statted, not the file that it refers to.
7090 The elements in @code{BUFF} are the same as described by @ref{STAT}.
7092 This intrinsic is provided in both subroutine and function forms; however,
7093 only one form can be used in any given program unit.
7095 @item @emph{Standard}:
7096 GNU extension
7098 @item @emph{Class}:
7099 Subroutine, function
7101 @item @emph{Syntax}:
7102 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
7104 @item @emph{Arguments}:
7105 @multitable @columnfractions .15 .70
7106 @item @var{FILE}   @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
7107 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7108 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 
7109                         on success and a system specific error code otherwise.
7110 @end multitable
7112 @item @emph{Example}:
7113 See @ref{STAT} for an example.
7115 @item @emph{See also}:
7116 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7117 @end table
7121 @node LTIME
7122 @section @code{LTIME} --- Convert time to local time info
7123 @fnindex LTIME
7124 @cindex time, conversion to local time info
7126 @table @asis
7127 @item @emph{Description}:
7128 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
7129 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
7130 to the local time zone using @code{localtime(3)}.
7132 @item @emph{Standard}:
7133 GNU extension
7135 @item @emph{Class}:
7136 Subroutine
7138 @item @emph{Syntax}:
7139 @code{CALL LTIME(STIME, TARRAY)}
7141 @item @emph{Arguments}:
7142 @multitable @columnfractions .15 .70
7143 @item @var{STIME}  @tab An @code{INTEGER(*)} scalar expression
7144                         corresponding to a system time, with 
7145                         @code{INTENT(IN)}.
7146 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
7147                         with @code{INTENT(OUT)}.
7148 @end multitable
7150 @item @emph{Return value}:
7151 The elements of @var{TARRAY} are assigned as follows:
7152 @enumerate
7153 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7154       seconds
7155 @item Minutes after the hour, range 0--59
7156 @item Hours past midnight, range 0--23
7157 @item Day of month, range 0--31
7158 @item Number of months since January, range 0--12
7159 @item Years since 1900
7160 @item Number of days since Sunday, range 0--6
7161 @item Days since January 1
7162 @item Daylight savings indicator: positive if daylight savings is in
7163       effect, zero if not, and negative if the information is not
7164       available.
7165 @end enumerate
7167 @item @emph{See also}:
7168 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7170 @end table
7174 @node MALLOC
7175 @section @code{MALLOC} --- Allocate dynamic memory
7176 @fnindex MALLOC
7177 @cindex pointer, cray
7179 @table @asis
7180 @item @emph{Description}:
7181 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7182 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7183 is an extension intended to be used with Cray pointers, and is provided
7184 in GNU Fortran to allow the user to compile legacy code. For new code
7185 using Fortran 95 pointers, the memory allocation intrinsic is
7186 @code{ALLOCATE}.
7188 @item @emph{Standard}:
7189 GNU extension
7191 @item @emph{Class}:
7192 Function
7194 @item @emph{Syntax}:
7195 @code{PTR = MALLOC(SIZE)}
7197 @item @emph{Arguments}:
7198 @multitable @columnfractions .15 .70
7199 @item @var{SIZE} @tab The type shall be @code{INTEGER(*)}.
7200 @end multitable
7202 @item @emph{Return value}:
7203 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7204 variables of type @code{INTEGER(K)} have the same size as
7205 C pointers (@code{sizeof(void *)}).
7207 @item @emph{Example}:
7208 The following example demonstrates the use of @code{MALLOC} and
7209 @code{FREE} with Cray pointers. This example is intended to run on
7210 32-bit systems, where the default integer kind is suitable to store
7211 pointers; on 64-bit systems, ptr_x would need to be declared as
7212 @code{integer(kind=8)}.
7214 @smallexample
7215 program test_malloc
7216   integer i
7217   integer ptr_x
7218   real*8 x(*), z
7219   pointer(ptr_x,x)
7221   ptr_x = malloc(20*8)
7222   do i = 1, 20
7223     x(i) = sqrt(1.0d0 / i)
7224   end do
7225   z = 0
7226   do i = 1, 20
7227     z = z + x(i)
7228     print *, z
7229   end do
7230   call free(ptr_x)
7231 end program test_malloc
7232 @end smallexample
7234 @item @emph{See also}:
7235 @ref{FREE}
7236 @end table
7240 @node MATMUL
7241 @section @code{MATMUL} --- matrix multiplication
7242 @fnindex MATMUL
7243 @cindex matrix multiplication
7244 @cindex product, matrix
7246 @table @asis
7247 @item @emph{Description}:
7248 Performs a matrix multiplication on numeric or logical arguments.
7250 @item @emph{Standard}:
7251 Fortran 95 and later
7253 @item @emph{Class}:
7254 Transformational function
7256 @item @emph{Syntax}:
7257 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7259 @item @emph{Arguments}:
7260 @multitable @columnfractions .15 .70
7261 @item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
7262                           @code{REAL(*)}, @code{COMPLEX(*)}, or
7263                           @code{LOGICAL(*)} type, with a rank of
7264                           one or two.
7265 @item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
7266                           @code{REAL(*)}, or @code{COMPLEX(*)} type if
7267                           @var{MATRIX_A} is of a numeric type;
7268                           otherwise, an array of @code{LOGICAL(*)}
7269                           type. The rank shall be one or two, and the
7270                           first (or only) dimension of @var{MATRIX_B}
7271                           shall be equal to the last (or only)
7272                           dimension of @var{MATRIX_A}.
7273 @end multitable
7275 @item @emph{Return value}:
7276 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
7277 kind of the result follow the usual type and kind promotion rules, as
7278 for the @code{*} or @code{.AND.} operators.
7280 @item @emph{See also}:
7281 @end table
7285 @node MAX
7286 @section @code{MAX} --- Maximum value of an argument list
7287 @fnindex MAX
7288 @fnindex MAX0
7289 @fnindex AMAX0
7290 @fnindex MAX1
7291 @fnindex AMAX1
7292 @fnindex DMAX1
7293 @cindex maximum value
7295 @table @asis
7296 @item @emph{Description}:
7297 Returns the argument with the largest (most positive) value.
7299 @item @emph{Standard}:
7300 Fortran 77 and later
7302 @item @emph{Class}:
7303 Elemental function
7305 @item @emph{Syntax}:
7306 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7308 @item @emph{Arguments}:
7309 @multitable @columnfractions .15 .70
7310 @item @var{A1}          @tab The type shall be @code{INTEGER(*)} or
7311                              @code{REAL(*)}.
7312 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7313                              as @var{A1}.  (As a GNU extension, 
7314                              arguments of different kinds are
7315                              permitted.)
7316 @end multitable
7318 @item @emph{Return value}:
7319 The return value corresponds to the maximum value among the arguments,
7320 and has the same type and kind as the first argument.
7322 @item @emph{Specific names}:
7323 @multitable @columnfractions .20 .20 .20 .25
7324 @item Name             @tab Argument            @tab Return type         @tab Standard
7325 @item @code{MAX0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
7326 @item @code{AMAX0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7327 @item @code{MAX1(X)}   @tab @code{REAL(*) X}    @tab @code{INT(MAX(X))}  @tab Fortran 77 and later
7328 @item @code{AMAX1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab Fortran 77 and later
7329 @item @code{DMAX1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab Fortran 77 and later
7330 @end multitable
7332 @item @emph{See also}:
7333 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7335 @end table
7339 @node MAXEXPONENT
7340 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7341 @fnindex MAXEXPONENT
7342 @cindex model representation, maximum exponent
7344 @table @asis
7345 @item @emph{Description}:
7346 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7347 type of @code{X}.
7349 @item @emph{Standard}:
7350 Fortran 95 and later
7352 @item @emph{Class}:
7353 Inquiry function
7355 @item @emph{Syntax}:
7356 @code{RESULT = MAXEXPONENT(X)}
7358 @item @emph{Arguments}:
7359 @multitable @columnfractions .15 .70
7360 @item @var{X} @tab Shall be of type @code{REAL}.
7361 @end multitable
7363 @item @emph{Return value}:
7364 The return value is of type @code{INTEGER} and of the default integer
7365 kind.
7367 @item @emph{Example}:
7368 @smallexample
7369 program exponents
7370   real(kind=4) :: x
7371   real(kind=8) :: y
7373   print *, minexponent(x), maxexponent(x)
7374   print *, minexponent(y), maxexponent(y)
7375 end program exponents
7376 @end smallexample
7377 @end table
7381 @node MAXLOC
7382 @section @code{MAXLOC} --- Location of the maximum value within an array
7383 @fnindex MAXLOC
7384 @cindex array, location of maximum element
7386 @table @asis
7387 @item @emph{Description}:
7388 Determines the location of the element in the array with the maximum
7389 value, or, if the @var{DIM} argument is supplied, determines the
7390 locations of the maximum element along each row of the array in the
7391 @var{DIM} direction.  If @var{MASK} is present, only the elements for
7392 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
7393 element in the array has the maximum value, the location returned is
7394 that of the first such element in array element order.  If the array has
7395 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7396 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
7397 and all of the elements of @var{MASK} along a given row are zero, the
7398 result value for that row is zero.
7400 @item @emph{Standard}:
7401 Fortran 95 and later
7403 @item @emph{Class}:
7404 Transformational function
7406 @item @emph{Syntax}:
7407 @multitable @columnfractions .80
7408 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7409 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7410 @end multitable
7412 @item @emph{Arguments}:
7413 @multitable @columnfractions .15 .70
7414 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7415                        @code{REAL(*)}, or @code{CHARACTER(*)}.
7416 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7417                        @code{INTEGER(*)}, with a value between one
7418                        and the rank of @var{ARRAY}, inclusive.  It
7419                        may not be an optional dummy argument.
7420 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
7421                        and conformable with @var{ARRAY}.
7422 @end multitable
7424 @item @emph{Return value}:
7425 If @var{DIM} is absent, the result is a rank-one array with a length
7426 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
7427 is an array with a rank one less than the rank of @var{ARRAY}, and a
7428 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7429 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
7430 of one, the result is a scalar.  In all cases, the result is of default
7431 @code{INTEGER} type.
7433 @item @emph{See also}:
7434 @ref{MAX}, @ref{MAXVAL}
7436 @end table
7440 @node MAXVAL
7441 @section @code{MAXVAL} --- Maximum value of an array
7442 @fnindex MAXVAL
7443 @cindex array, maximum value
7444 @cindex maximum value
7446 @table @asis
7447 @item @emph{Description}:
7448 Determines the maximum value of the elements in an array value, or, if
7449 the @var{DIM} argument is supplied, determines the maximum value along
7450 each row of the array in the @var{DIM} direction.  If @var{MASK} is
7451 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7452 considered.  If the array has zero size, or all of the elements of
7453 @var{MASK} are @code{.FALSE.}, then the result is the most negative
7454 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
7455 a string of nulls if @var{ARRAY} is of character type.
7457 @item @emph{Standard}:
7458 Fortran 95 and later
7460 @item @emph{Class}:
7461 Transformational function
7463 @item @emph{Syntax}:
7464 @multitable @columnfractions .80
7465 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7466 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7467 @end multitable
7469 @item @emph{Arguments}:
7470 @multitable @columnfractions .15 .70
7471 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7472                        @code{REAL(*)}, or @code{CHARACTER(*)}.
7473 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7474                        @code{INTEGER(*)}, with a value between one
7475                        and the rank of @var{ARRAY}, inclusive.  It
7476                        may not be an optional dummy argument.
7477 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
7478                        and conformable with @var{ARRAY}.
7479 @end multitable
7481 @item @emph{Return value}:
7482 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7483 is a scalar.  If @var{DIM} is present, the result is an array with a
7484 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7485 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
7486 cases, the result is of the same type and kind as @var{ARRAY}.
7488 @item @emph{See also}:
7489 @ref{MAX}, @ref{MAXLOC}
7490 @end table
7494 @node MCLOCK
7495 @section @code{MCLOCK} --- Time function
7496 @fnindex MCLOCK
7497 @cindex time, clock ticks
7498 @cindex clock ticks
7500 @table @asis
7501 @item @emph{Description}:
7502 Returns the number of clock ticks since the start of the process, based
7503 on the UNIX function @code{clock(3)}.
7505 This intrinsic is not fully portable, such as to systems with 32-bit
7506 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7507 the values returned by this intrinsic might be, or become, negative, or
7508 numerically less than previous values, during a single run of the
7509 compiled program.
7511 @item @emph{Standard}:
7512 GNU extension
7514 @item @emph{Class}:
7515 Function
7517 @item @emph{Syntax}:
7518 @code{RESULT = MCLOCK()}
7520 @item @emph{Return value}:
7521 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7522 number of clock ticks since the start of the process, or @code{-1} if
7523 the system does not support @code{clock(3)}.
7525 @item @emph{See also}:
7526 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7528 @end table
7532 @node MCLOCK8
7533 @section @code{MCLOCK8} --- Time function (64-bit)
7534 @fnindex MCLOCK8
7535 @cindex time, clock ticks
7536 @cindex clock ticks
7538 @table @asis
7539 @item @emph{Description}:
7540 Returns the number of clock ticks since the start of the process, based
7541 on the UNIX function @code{clock(3)}.
7543 @emph{Warning:} this intrinsic does not increase the range of the timing
7544 values over that returned by @code{clock(3)}. On a system with a 32-bit
7545 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7546 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7547 overflows of the 32-bit value can still occur. Therefore, the values
7548 returned by this intrinsic might be or become negative or numerically
7549 less than previous values during a single run of the compiled program.
7551 @item @emph{Standard}:
7552 GNU extension
7554 @item @emph{Class}:
7555 Function
7557 @item @emph{Syntax}:
7558 @code{RESULT = MCLOCK8()}
7560 @item @emph{Return value}:
7561 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7562 number of clock ticks since the start of the process, or @code{-1} if
7563 the system does not support @code{clock(3)}.
7565 @item @emph{See also}:
7566 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7568 @end table
7572 @node MERGE
7573 @section @code{MERGE} --- Merge variables
7574 @fnindex MERGE
7575 @cindex array, merge arrays
7576 @cindex array, combine arrays
7578 @table @asis
7579 @item @emph{Description}:
7580 Select values from two arrays according to a logical mask.  The result
7581 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7582 @var{FSOURCE} if it is @code{.FALSE.}.
7584 @item @emph{Standard}:
7585 Fortran 95 and later
7587 @item @emph{Class}:
7588 Elemental function
7590 @item @emph{Syntax}:
7591 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7593 @item @emph{Arguments}:
7594 @multitable @columnfractions .15 .70
7595 @item @var{TSOURCE} @tab May be of any type.
7596 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7597                          as @var{TSOURCE}.
7598 @item @var{MASK}    @tab Shall be of type @code{LOGICAL(*)}.
7599 @end multitable
7601 @item @emph{Return value}:
7602 The result is of the same type and type parameters as @var{TSOURCE}.
7604 @end table
7608 @node MIN
7609 @section @code{MIN} --- Minimum value of an argument list
7610 @fnindex MIN
7611 @fnindex MIN0
7612 @fnindex AMIN0
7613 @fnindex MIN1
7614 @fnindex AMIN1
7615 @fnindex DMIN1
7616 @cindex minimum value
7618 @table @asis
7619 @item @emph{Description}:
7620 Returns the argument with the smallest (most negative) value.
7622 @item @emph{Standard}:
7623 Fortran 77 and later
7625 @item @emph{Class}:
7626 Elemental function
7628 @item @emph{Syntax}:
7629 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7631 @item @emph{Arguments}:
7632 @multitable @columnfractions .15 .70
7633 @item @var{A1}          @tab The type shall be @code{INTEGER(*)} or
7634                              @code{REAL(*)}.
7635 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7636                              as @var{A1}.  (As a GNU extension, 
7637                              arguments of different kinds are
7638                              permitted.)
7639 @end multitable
7641 @item @emph{Return value}:
7642 The return value corresponds to the maximum value among the arguments,
7643 and has the same type and kind as the first argument.
7645 @item @emph{Specific names}:
7646 @multitable @columnfractions .20 .20 .20 .25
7647 @item Name             @tab Argument            @tab Return type         @tab Standard
7648 @item @code{MIN0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
7649 @item @code{AMIN0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab Fortran 77 and later
7650 @item @code{MIN1(X)}   @tab @code{REAL(*) X}    @tab @code{INT(MIN(X))}  @tab Fortran 77 and later
7651 @item @code{AMIN1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab Fortran 77 and later
7652 @item @code{DMIN1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab Fortran 77 and later
7653 @end multitable
7655 @item @emph{See also}:
7656 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7657 @end table
7661 @node MINEXPONENT
7662 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7663 @fnindex MINEXPONENT
7664 @cindex model representation, minimum exponent
7666 @table @asis
7667 @item @emph{Description}:
7668 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7669 type of @code{X}.
7671 @item @emph{Standard}:
7672 Fortran 95 and later
7674 @item @emph{Class}:
7675 Inquiry function
7677 @item @emph{Syntax}:
7678 @code{RESULT = MINEXPONENT(X)}
7680 @item @emph{Arguments}:
7681 @multitable @columnfractions .15 .70
7682 @item @var{X} @tab Shall be of type @code{REAL}.
7683 @end multitable
7685 @item @emph{Return value}:
7686 The return value is of type @code{INTEGER} and of the default integer
7687 kind.
7689 @item @emph{Example}:
7690 See @code{MAXEXPONENT} for an example.
7691 @end table
7695 @node MINLOC
7696 @section @code{MINLOC} --- Location of the minimum value within an array
7697 @fnindex MINLOC
7698 @cindex array, location of minimum element
7700 @table @asis
7701 @item @emph{Description}:
7702 Determines the location of the element in the array with the minimum
7703 value, or, if the @var{DIM} argument is supplied, determines the
7704 locations of the minimum element along each row of the array in the
7705 @var{DIM} direction.  If @var{MASK} is present, only the elements for
7706 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
7707 element in the array has the minimum value, the location returned is
7708 that of the first such element in array element order.  If the array has
7709 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7710 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
7711 and all of the elements of @var{MASK} along a given row are zero, the
7712 result value for that row is zero.
7714 @item @emph{Standard}:
7715 Fortran 95 and later
7717 @item @emph{Class}:
7718 Transformational function
7720 @item @emph{Syntax}:
7721 @multitable @columnfractions .80
7722 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7723 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7724 @end multitable
7726 @item @emph{Arguments}:
7727 @multitable @columnfractions .15 .70
7728 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7729                        @code{REAL(*)}, or @code{CHARACTER(*)}.
7730 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7731                        @code{INTEGER(*)}, with a value between one
7732                        and the rank of @var{ARRAY}, inclusive.  It
7733                        may not be an optional dummy argument.
7734 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
7735                        and conformable with @var{ARRAY}.
7736 @end multitable
7738 @item @emph{Return value}:
7739 If @var{DIM} is absent, the result is a rank-one array with a length
7740 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
7741 is an array with a rank one less than the rank of @var{ARRAY}, and a
7742 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7743 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
7744 of one, the result is a scalar.  In all cases, the result is of default
7745 @code{INTEGER} type.
7747 @item @emph{See also}:
7748 @ref{MIN}, @ref{MINVAL}
7750 @end table
7754 @node MINVAL
7755 @section @code{MINVAL} --- Minimum value of an array
7756 @fnindex MINVAL
7757 @cindex array, minimum value
7758 @cindex minimum value
7760 @table @asis
7761 @item @emph{Description}:
7762 Determines the minimum value of the elements in an array value, or, if
7763 the @var{DIM} argument is supplied, determines the minimum value along
7764 each row of the array in the @var{DIM} direction.  If @var{MASK} is
7765 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7766 considered.  If the array has zero size, or all of the elements of
7767 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7768 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7769 @var{ARRAY} is of character type.
7771 @item @emph{Standard}:
7772 Fortran 95 and later
7774 @item @emph{Class}:
7775 Transformational function
7777 @item @emph{Syntax}:
7778 @multitable @columnfractions .80
7779 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7780 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7781 @end multitable
7783 @item @emph{Arguments}:
7784 @multitable @columnfractions .15 .70
7785 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7786                        @code{REAL(*)}, or @code{CHARACTER(*)}.
7787 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7788                        @code{INTEGER(*)}, with a value between one
7789                        and the rank of @var{ARRAY}, inclusive.  It
7790                        may not be an optional dummy argument.
7791 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
7792                        and conformable with @var{ARRAY}.
7793 @end multitable
7795 @item @emph{Return value}:
7796 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7797 is a scalar.  If @var{DIM} is present, the result is an array with a
7798 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7799 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
7800 cases, the result is of the same type and kind as @var{ARRAY}.
7802 @item @emph{See also}:
7803 @ref{MIN}, @ref{MINLOC}
7805 @end table
7809 @node MOD
7810 @section @code{MOD} --- Remainder function
7811 @fnindex MOD
7812 @fnindex AMOD
7813 @fnindex DMOD
7814 @cindex remainder
7815 @cindex division, remainder
7817 @table @asis
7818 @item @emph{Description}:
7819 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7820 calculated as @code{A - (INT(A/P) * P)}.
7822 @item @emph{Standard}:
7823 Fortran 77 and later
7825 @item @emph{Class}:
7826 Elemental function
7828 @item @emph{Syntax}:
7829 @code{RESULT = MOD(A, P)}
7831 @item @emph{Arguments}:
7832 @multitable @columnfractions .15 .70
7833 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7834 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7835 equal to zero
7836 @end multitable
7838 @item @emph{Return value}:
7839 The kind of the return value is the result of cross-promoting
7840 the kinds of the arguments.
7842 @item @emph{Example}:
7843 @smallexample
7844 program test_mod
7845   print *, mod(17,3)
7846   print *, mod(17.5,5.5)
7847   print *, mod(17.5d0,5.5)
7848   print *, mod(17.5,5.5d0)
7850   print *, mod(-17,3)
7851   print *, mod(-17.5,5.5)
7852   print *, mod(-17.5d0,5.5)
7853   print *, mod(-17.5,5.5d0)
7855   print *, mod(17,-3)
7856   print *, mod(17.5,-5.5)
7857   print *, mod(17.5d0,-5.5)
7858   print *, mod(17.5,-5.5d0)
7859 end program test_mod
7860 @end smallexample
7862 @item @emph{Specific names}:
7863 @multitable @columnfractions .20 .20 .20 .25
7864 @item Name             @tab Arguments      @tab Return type    @tab Standard
7865 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab Fortran 95 and later
7866 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab Fortran 95 and later
7867 @end multitable
7868 @end table
7872 @node MODULO
7873 @section @code{MODULO} --- Modulo function
7874 @fnindex MODULO
7875 @cindex modulo
7876 @cindex division, modulo
7878 @table @asis
7879 @item @emph{Description}:
7880 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7882 @item @emph{Standard}:
7883 Fortran 95 and later
7885 @item @emph{Class}:
7886 Elemental function
7888 @item @emph{Syntax}:
7889 @code{RESULT = MODULO(A, P)}
7891 @item @emph{Arguments}:
7892 @multitable @columnfractions .15 .70
7893 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7894 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7895 @end multitable
7897 @item @emph{Return value}:
7898 The type and kind of the result are those of the arguments.
7899 @table @asis
7900 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7901 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7902 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7903 (exclusive).
7904 @item If @var{A} and @var{P} are of type @code{REAL}:
7905 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7906 @end table
7907 In all cases, if @var{P} is zero the result is processor-dependent.
7909 @item @emph{Example}:
7910 @smallexample
7911 program test_modulo
7912   print *, modulo(17,3)
7913   print *, modulo(17.5,5.5)
7915   print *, modulo(-17,3)
7916   print *, modulo(-17.5,5.5)
7918   print *, modulo(17,-3)
7919   print *, modulo(17.5,-5.5)
7920 end program
7921 @end smallexample
7923 @end table
7927 @node MOVE_ALLOC
7928 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7929 @fnindex MOVE_ALLOC
7930 @cindex moving allocation
7931 @cindex allocation, moving
7933 @table @asis
7934 @item @emph{Description}:
7935 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7936 @var{DEST}.  @var{SRC} will become deallocated in the process.
7938 @item @emph{Standard}:
7939 Fortran 2003 and later
7941 @item @emph{Class}:
7942 Subroutine
7944 @item @emph{Syntax}:
7945 @code{CALL MOVE_ALLOC(SRC, DEST)}
7947 @item @emph{Arguments}:
7948 @multitable @columnfractions .15 .70
7949 @item @var{SRC}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
7950                       of any type and kind.
7951 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
7952                       of the same type, kind and rank as @var{SRC}
7953 @end multitable
7955 @item @emph{Return value}:
7956 None
7958 @item @emph{Example}:
7959 @smallexample
7960 program test_move_alloc
7961     integer, allocatable :: a(:), b(:)
7963     allocate(a(3))
7964     a = [ 1, 2, 3 ]
7965     call move_alloc(a, b)
7966     print *, allocated(a), allocated(b)
7967     print *, b
7968 end program test_move_alloc
7969 @end smallexample
7970 @end table
7974 @node MVBITS
7975 @section @code{MVBITS} --- Move bits from one integer to another
7976 @fnindex MVBITS
7977 @cindex bits, move
7979 @table @asis
7980 @item @emph{Description}:
7981 Moves @var{LEN} bits from positions @var{FROMPOS} through
7982 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
7983 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
7984 affected by the movement of bits is unchanged. The values of
7985 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
7986 @code{BIT_SIZE(FROM)}.
7988 @item @emph{Standard}:
7989 Fortran 95 and later
7991 @item @emph{Class}:
7992 Elemental subroutine
7994 @item @emph{Syntax}:
7995 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
7997 @item @emph{Arguments}:
7998 @multitable @columnfractions .15 .70
7999 @item @var{FROM}    @tab The type shall be @code{INTEGER(*)}.
8000 @item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
8001 @item @var{LEN}     @tab The type shall be @code{INTEGER(*)}.
8002 @item @var{TO}      @tab The type shall be @code{INTEGER(*)}, of the
8003                          same kind as @var{FROM}.
8004 @item @var{TOPOS}   @tab The type shall be @code{INTEGER(*)}.
8005 @end multitable
8007 @item @emph{See also}:
8008 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8009 @end table
8013 @node NEAREST
8014 @section @code{NEAREST} --- Nearest representable number
8015 @fnindex NEAREST
8016 @cindex real number, nearest different
8017 @cindex floating point, nearest different
8019 @table @asis
8020 @item @emph{Description}:
8021 @code{NEAREST(X, S)} returns the processor-representable number nearest
8022 to @code{X} in the direction indicated by the sign of @code{S}.
8024 @item @emph{Standard}:
8025 Fortran 95 and later
8027 @item @emph{Class}:
8028 Elemental function
8030 @item @emph{Syntax}:
8031 @code{RESULT = NEAREST(X, S)}
8033 @item @emph{Arguments}:
8034 @multitable @columnfractions .15 .70
8035 @item @var{X} @tab Shall be of type @code{REAL}.
8036 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8037 not equal to zero.
8038 @end multitable
8040 @item @emph{Return value}:
8041 The return value is of the same type as @code{X}. If @code{S} is
8042 positive, @code{NEAREST} returns the processor-representable number
8043 greater than @code{X} and nearest to it. If @code{S} is negative,
8044 @code{NEAREST} returns the processor-representable number smaller than
8045 @code{X} and nearest to it.
8047 @item @emph{Example}:
8048 @smallexample
8049 program test_nearest
8050   real :: x, y
8051   x = nearest(42.0, 1.0)
8052   y = nearest(42.0, -1.0)
8053   write (*,"(3(G20.15))") x, y, x - y
8054 end program test_nearest
8055 @end smallexample
8056 @end table
8060 @node NEW_LINE
8061 @section @code{NEW_LINE} --- New line character
8062 @fnindex NEW_LINE
8063 @cindex newline
8064 @cindex output, newline
8066 @table @asis
8067 @item @emph{Description}:
8068 @code{NEW_LINE(C)} returns the new-line character.
8070 @item @emph{Standard}:
8071 Fortran 2003 and later
8073 @item @emph{Class}:
8074 Inquiry function
8076 @item @emph{Syntax}:
8077 @code{RESULT = NEW_LINE(C)}
8079 @item @emph{Arguments}:
8080 @multitable @columnfractions .15 .70
8081 @item @var{C}    @tab The argument shall be a scalar or array of the
8082                       type @code{CHARACTER}.
8083 @end multitable
8085 @item @emph{Return value}:
8086 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8087 the same kind as parameter @var{C}.
8089 @item @emph{Example}:
8090 @smallexample
8091 program newline
8092   implicit none
8093   write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8094 end program newline
8095 @end smallexample
8096 @end table
8100 @node NINT
8101 @section @code{NINT} --- Nearest whole number
8102 @fnindex NINT
8103 @fnindex IDNINT
8104 @cindex rounding, nearest whole number
8106 @table @asis
8107 @item @emph{Description}:
8108 @code{NINT(X)} rounds its argument to the nearest whole number.
8110 @item @emph{Standard}:
8111 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8113 @item @emph{Class}:
8114 Elemental function
8116 @item @emph{Syntax}:
8117 @code{RESULT = NINT(X [, KIND])}
8119 @item @emph{Arguments}:
8120 @multitable @columnfractions .15 .70
8121 @item @var{X}    @tab The type of the argument shall be @code{REAL}.
8122 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8123                       expression indicating the kind parameter of
8124                       the result.
8125 @end multitable
8127 @item @emph{Return value}:
8128 Returns @var{A} with the fractional portion of its magnitude eliminated by
8129 rounding to the nearest whole number and with its sign preserved,
8130 converted to an @code{INTEGER} of the default kind.
8132 @item @emph{Example}:
8133 @smallexample
8134 program test_nint
8135   real(4) x4
8136   real(8) x8
8137   x4 = 1.234E0_4
8138   x8 = 4.321_8
8139   print *, nint(x4), idnint(x8)
8140 end program test_nint
8141 @end smallexample
8143 @item @emph{Specific names}:
8144 @multitable @columnfractions .25 .25 .25
8145 @item Name             @tab Argument         @tab Standard
8146 @item @code{IDNINT(X)} @tab @code{REAL(8)}   @tab Fortran 95 and later
8147 @end multitable
8149 @item @emph{See also}:
8150 @ref{CEILING}, @ref{FLOOR}
8152 @end table
8156 @node NOT
8157 @section @code{NOT} --- Logical negation
8158 @fnindex NOT
8159 @cindex bits, negate
8160 @cindex bitwise logical not
8161 @cindex logical not, bitwise
8163 @table @asis
8164 @item @emph{Description}:
8165 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8167 @item @emph{Standard}:
8168 Fortran 95 and later
8170 @item @emph{Class}:
8171 Elemental function
8173 @item @emph{Syntax}:
8174 @code{RESULT = NOT(I)}
8176 @item @emph{Arguments}:
8177 @multitable @columnfractions .15 .70
8178 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
8179 @end multitable
8181 @item @emph{Return value}:
8182 The return type is @code{INTEGER(*)}, of the same kind as the
8183 argument.
8185 @item @emph{See also}:
8186 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8188 @end table
8192 @node NULL
8193 @section @code{NULL} --- Function that returns an disassociated pointer
8194 @fnindex NULL
8195 @cindex pointer, status
8196 @cindex pointer, disassociated
8198 @table @asis
8199 @item @emph{Description}:
8200 Returns a disassociated pointer.
8202 If @var{MOLD} is present, a dissassociated pointer of the same type is
8203 returned, otherwise the type is determined by context.
8205 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8206 includes cases where it is required.
8208 @item @emph{Standard}:
8209 Fortran 95 and later
8211 @item @emph{Class}:
8212 Transformational function
8214 @item @emph{Syntax}:
8215 @code{PTR => NULL([MOLD])}
8217 @item @emph{Arguments}:
8218 @multitable @columnfractions .15 .70
8219 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8220 status and of any type.
8221 @end multitable
8223 @item @emph{Return value}:
8224 A disassociated pointer.
8226 @item @emph{Example}:
8227 @smallexample
8228 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8229 @end smallexample
8231 @item @emph{See also}:
8232 @ref{ASSOCIATED}
8233 @end table
8237 @node OR
8238 @section @code{OR} --- Bitwise logical OR
8239 @fnindex OR
8240 @cindex bitwise logical or
8241 @cindex logical or, bitwise
8243 @table @asis
8244 @item @emph{Description}:
8245 Bitwise logical @code{OR}.
8247 This intrinsic routine is provided for backwards compatibility with 
8248 GNU Fortran 77.  For integer arguments, programmers should consider
8249 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8251 @item @emph{Standard}:
8252 GNU extension
8254 @item @emph{Class}:
8255 Function
8257 @item @emph{Syntax}:
8258 @code{RESULT = OR(X, Y)}
8260 @item @emph{Arguments}:
8261 @multitable @columnfractions .15 .70
8262 @item @var{X} @tab The type shall be either a scalar @code{INTEGER(*)}
8263 type or a scalar @code{LOGICAL} type.
8264 @item @var{Y} @tab The type shall be the same as the type of @var{X}.
8265 @end multitable
8267 @item @emph{Return value}:
8268 The return type is either a scalar @code{INTEGER(*)} or a scalar
8269 @code{LOGICAL}.  If the kind type parameters differ, then the
8270 smaller kind type is implicitly converted to larger kind, and the 
8271 return has the larger kind.
8273 @item @emph{Example}:
8274 @smallexample
8275 PROGRAM test_or
8276   LOGICAL :: T = .TRUE., F = .FALSE.
8277   INTEGER :: a, b
8278   DATA a / Z'F' /, b / Z'3' /
8280   WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8281   WRITE (*,*) OR(a, b)
8282 END PROGRAM
8283 @end smallexample
8285 @item @emph{See also}:
8286 Fortran 95 elemental function: @ref{IOR}
8287 @end table
8291 @node PACK
8292 @section @code{PACK} --- Pack an array into an array of rank one
8293 @fnindex PACK
8294 @cindex array, packing
8295 @cindex array, reduce dimension
8296 @cindex array, gather elements
8298 @table @asis
8299 @item @emph{Description}:
8300 Stores the elements of @var{ARRAY} in an array of rank one.
8302 The beginning of the resulting array is made up of elements whose @var{MASK} 
8303 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8304 @var{VECTOR}.
8306 @item @emph{Standard}:
8307 Fortran 95 and later
8309 @item @emph{Class}:
8310 Transformational function
8312 @item @emph{Syntax}:
8313 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8315 @item @emph{Arguments}:
8316 @multitable @columnfractions .15 .70
8317 @item @var{ARRAY}  @tab Shall be an array of any type.
8318 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and 
8319 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} 
8320 scalar.
8321 @item @var{VECTOR} @tab (Optional) shall be an array of the same type 
8322 as @var{ARRAY} and of rank one. If present, the number of elements in 
8323 @var{VECTOR} shall be equal to or greater than the number of true elements 
8324 in @var{MASK}. If @var{MASK} is scalar, the number of elements in 
8325 @var{VECTOR} shall be equal to or greater than the number of elements in
8326 @var{ARRAY}.
8327 @end multitable
8329 @item @emph{Return value}:
8330 The result is an array of rank one and the same type as that of @var{ARRAY}.
8331 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8332 number of @code{TRUE} values in @var{MASK} otherwise.
8334 @item @emph{Example}:
8335 Gathering nonzero elements from an array:
8336 @smallexample
8337 PROGRAM test_pack_1
8338   INTEGER :: m(6)
8339   m = (/ 1, 0, 0, 0, 5, 0 /)
8340   WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
8341 END PROGRAM
8342 @end smallexample
8344 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8345 @smallexample
8346 PROGRAM test_pack_2
8347   INTEGER :: m(4)
8348   m = (/ 1, 0, 0, 2 /)
8349   WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
8350 END PROGRAM
8351 @end smallexample
8353 @item @emph{See also}:
8354 @ref{UNPACK}
8355 @end table
8359 @node PERROR
8360 @section @code{PERROR} --- Print system error message
8361 @fnindex PERROR
8362 @cindex system, error handling
8364 @table @asis
8365 @item @emph{Description}:
8366 Prints (on the C @code{stderr} stream) a newline-terminated error
8367 message corresponding to the last system error. This is prefixed by
8368 @var{STRING}, a colon and a space. See @code{perror(3)}.
8370 @item @emph{Standard}:
8371 GNU extension
8373 @item @emph{Class}:
8374 Subroutine
8376 @item @emph{Syntax}:
8377 @code{CALL PERROR(STRING)}
8379 @item @emph{Arguments}:
8380 @multitable @columnfractions .15 .70
8381 @item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
8382 @end multitable
8384 @item @emph{See also}:
8385 @ref{IERRNO}
8386 @end table
8390 @node PRECISION
8391 @section @code{PRECISION} --- Decimal precision of a real kind
8392 @fnindex PRECISION
8393 @cindex model representation, precision
8395 @table @asis
8396 @item @emph{Description}:
8397 @code{PRECISION(X)} returns the decimal precision in the model of the
8398 type of @code{X}.
8400 @item @emph{Standard}:
8401 Fortran 95 and later
8403 @item @emph{Class}:
8404 Inquiry function
8406 @item @emph{Syntax}:
8407 @code{RESULT = PRECISION(X)}
8409 @item @emph{Arguments}:
8410 @multitable @columnfractions .15 .70
8411 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8412 @end multitable
8414 @item @emph{Return value}:
8415 The return value is of type @code{INTEGER} and of the default integer
8416 kind.
8418 @item @emph{Example}:
8419 @smallexample
8420 program prec_and_range
8421   real(kind=4) :: x(2)
8422   complex(kind=8) :: y
8424   print *, precision(x), range(x)
8425   print *, precision(y), range(y)
8426 end program prec_and_range
8427 @end smallexample
8428 @end table
8432 @node PRESENT
8433 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8434 @fnindex PRESENT
8436 @table @asis
8437 @item @emph{Description}:
8438 Determines whether an optional dummy argument is present.
8440 @item @emph{Standard}:
8441 Fortran 95 and later
8443 @item @emph{Class}:
8444 Inquiry function
8446 @item @emph{Syntax}:
8447 @code{RESULT = PRESENT(A)}
8449 @item @emph{Arguments}:
8450 @multitable @columnfractions .15 .70
8451 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8452 value, or a dummy procedure. It shall be the name of an optional dummy argument
8453 accessible within the current subroutine or function.
8454 @end multitable
8456 @item @emph{Return value}:
8457 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8458 @code{FALSE} otherwise.
8460 @item @emph{Example}:
8461 @smallexample
8462 PROGRAM test_present
8463   WRITE(*,*) f(), f(42)      ! "F T"
8464 CONTAINS
8465   LOGICAL FUNCTION f(x)
8466     INTEGER, INTENT(IN), OPTIONAL :: x
8467     f = PRESENT(x)
8468   END FUNCTION
8469 END PROGRAM
8470 @end smallexample
8471 @end table
8475 @node PRODUCT
8476 @section @code{PRODUCT} --- Product of array elements
8477 @fnindex PRODUCT
8478 @cindex array, product
8479 @cindex array, multiply elements
8480 @cindex array, conditionally multiply elements
8481 @cindex multiply array elements
8483 @table @asis
8484 @item @emph{Description}:
8485 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8486 the corresponding element in @var{MASK} is @code{TRUE}.
8488 @item @emph{Standard}:
8489 Fortran 95 and later
8491 @item @emph{Class}:
8492 Transformational function
8494 @item @emph{Syntax}:
8495 @code{RESULT = PRODUCT(ARRAY[, MASK])}
8496 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8498 @item @emph{Arguments}:
8499 @multitable @columnfractions .15 .70
8500 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)}, 
8501 @code{REAL(*)} or @code{COMPLEX(*)}.
8502 @item @var{DIM}   @tab (Optional) shall be a scalar of type 
8503 @code{INTEGER} with a value in the range from 1 to n, where n 
8504 equals the rank of @var{ARRAY}.
8505 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL} 
8506 and either be a scalar or an array of the same shape as @var{ARRAY}.
8507 @end multitable
8509 @item @emph{Return value}:
8510 The result is of the same type as @var{ARRAY}.
8512 If @var{DIM} is absent, a scalar with the product of all elements in 
8513 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 
8514 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 
8515 dimension @var{DIM} dropped is returned.
8518 @item @emph{Example}:
8519 @smallexample
8520 PROGRAM test_product
8521   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8522   print *, PRODUCT(x)                    ! all elements, product = 120
8523   print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8524 END PROGRAM
8525 @end smallexample
8527 @item @emph{See also}:
8528 @ref{SUM}
8529 @end table
8533 @node RADIX
8534 @section @code{RADIX} --- Base of a model number
8535 @fnindex RADIX
8536 @cindex model representation, base
8537 @cindex model representation, radix
8539 @table @asis
8540 @item @emph{Description}:
8541 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8543 @item @emph{Standard}:
8544 Fortran 95 and later
8546 @item @emph{Class}:
8547 Inquiry function
8549 @item @emph{Syntax}:
8550 @code{RESULT = RADIX(X)}
8552 @item @emph{Arguments}:
8553 @multitable @columnfractions .15 .70
8554 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8555 @end multitable
8557 @item @emph{Return value}:
8558 The return value is a scalar of type @code{INTEGER} and of the default
8559 integer kind.
8561 @item @emph{Example}:
8562 @smallexample
8563 program test_radix
8564   print *, "The radix for the default integer kind is", radix(0)
8565   print *, "The radix for the default real kind is", radix(0.0)
8566 end program test_radix
8567 @end smallexample
8569 @end table
8573 @node RAN
8574 @section @code{RAN} --- Real pseudo-random number
8575 @fnindex RAN
8576 @cindex random number generation
8578 @table @asis
8579 @item @emph{Description}:
8580 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8581 provided as an alias for @code{RAND}.  See @ref{RAND} for complete
8582 documentation.
8584 @item @emph{Standard}:
8585 GNU extension
8587 @item @emph{Class}:
8588 Function
8590 @item @emph{See also}:
8591 @ref{RAND}, @ref{RANDOM_NUMBER}
8592 @end table
8596 @node RAND
8597 @section @code{RAND} --- Real pseudo-random number
8598 @fnindex RAND
8599 @cindex random number generation
8601 @table @asis
8602 @item @emph{Description}:
8603 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8604 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8605 in the current sequence is returned; if @var{FLAG} is 1, the generator
8606 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8607 it is used as a new seed with @code{SRAND}.
8609 This intrinsic routine is provided for backwards compatibility with
8610 GNU Fortran 77. It implements a simple modulo generator as provided 
8611 by @command{g77}. For new code, one should consider the use of 
8612 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8614 @item @emph{Standard}:
8615 GNU extension
8617 @item @emph{Class}:
8618 Function
8620 @item @emph{Syntax}:
8621 @code{RESULT = RAND(FLAG)}
8623 @item @emph{Arguments}:
8624 @multitable @columnfractions .15 .70
8625 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
8626 @end multitable
8628 @item @emph{Return value}:
8629 The return value is of @code{REAL} type and the default kind.
8631 @item @emph{Example}:
8632 @smallexample
8633 program test_rand
8634   integer,parameter :: seed = 86456
8635   
8636   call srand(seed)
8637   print *, rand(), rand(), rand(), rand()
8638   print *, rand(seed), rand(), rand(), rand()
8639 end program test_rand
8640 @end smallexample
8642 @item @emph{See also}:
8643 @ref{SRAND}, @ref{RANDOM_NUMBER}
8645 @end table
8649 @node RANDOM_NUMBER
8650 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8651 @fnindex RANDOM_NUMBER
8652 @cindex random number generation
8654 @table @asis
8655 @item @emph{Description}:
8656 Returns a single pseudorandom number or an array of pseudorandom numbers
8657 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8659 The runtime-library implements George Marsaglia's KISS (Keep It Simple 
8660 Stupid) random number generator (RNG). This RNG combines:
8661 @enumerate
8662 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8663 with a period of @math{2^{32}},
8664 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8665 @item  Two 16-bit multiply-with-carry generators with a period of
8666 @math{597273182964842497 > 2^{59}}.
8667 @end enumerate
8668 The overall period exceeds @math{2^{123}}.
8670 Please note, this RNG is thread safe if used within OpenMP directives,
8671 i.e., its state will be consistent while called from multiple threads.
8672 However, the KISS generator does not create random numbers in parallel 
8673 from multiple sources, but in sequence from a single source. If an
8674 OpenMP-enabled application heavily relies on random numbers, one should 
8675 consider employing a dedicated parallel random number generator instead.
8677 @item @emph{Standard}:
8678 Fortran 95 and later
8680 @item @emph{Class}:
8681 Subroutine
8683 @item @emph{Syntax}:
8684 @code{RANDOM_NUMBER(HARVEST)}
8686 @item @emph{Arguments}:
8687 @multitable @columnfractions .15 .70
8688 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
8689 @end multitable
8691 @item @emph{Example}:
8692 @smallexample
8693 program test_random_number
8694   REAL :: r(5,5)
8695   CALL init_random_seed()         ! see example of RANDOM_SEED
8696   CALL RANDOM_NUMBER(r)
8697 end program
8698 @end smallexample
8700 @item @emph{See also}:
8701 @ref{RANDOM_SEED}
8702 @end table
8706 @node RANDOM_SEED
8707 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8708 @fnindex RANDOM_SEED
8709 @cindex random number generation, seeding
8710 @cindex seeding a random number generator
8712 @table @asis
8713 @item @emph{Description}:
8714 Restarts or queries the state of the pseudorandom number generator used by 
8715 @code{RANDOM_NUMBER}.
8717 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8718 a default state. The example below shows how to initialize the random 
8719 seed based on the system's time.
8721 @item @emph{Standard}:
8722 Fortran 95 and later
8724 @item @emph{Class}:
8725 Subroutine
8727 @item @emph{Syntax}:
8728 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8730 @item @emph{Arguments}:
8731 @multitable @columnfractions .15 .70
8732 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default 
8733 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size 
8734 of the arrays used with the @var{PUT} and @var{GET} arguments.
8735 @item @var{PUT}  @tab (Optional) Shall be an array of type default 
8736 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of 
8737 the array must be larger than or equal to the number returned by the 
8738 @var{SIZE} argument.
8739 @item @var{GET}  @tab (Optional) Shall be an array of type default 
8740 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size 
8741 of the array must be larger than or equal to the number returned by 
8742 the @var{SIZE} argument.
8743 @end multitable
8745 @item @emph{Example}:
8746 @smallexample
8747 SUBROUTINE init_random_seed()
8748   INTEGER :: i, n, clock
8749   INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8751   CALL RANDOM_SEED(size = n)
8752   ALLOCATE(seed(n))
8754   CALL SYSTEM_CLOCK(COUNT=clock)
8756   seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8757   CALL RANDOM_SEED(PUT = seed)
8759   DEALLOCATE(seed)
8760 END SUBROUTINE
8761 @end smallexample
8763 @item @emph{See also}:
8764 @ref{RANDOM_NUMBER}
8765 @end table
8769 @node RANGE
8770 @section @code{RANGE} --- Decimal exponent range of a real kind
8771 @fnindex RANGE
8772 @cindex model representation, range
8774 @table @asis
8775 @item @emph{Description}:
8776 @code{RANGE(X)} returns the decimal exponent range in the model of the
8777 type of @code{X}.
8779 @item @emph{Standard}:
8780 Fortran 95 and later
8782 @item @emph{Class}:
8783 Inquiry function
8785 @item @emph{Syntax}:
8786 @code{RESULT = RANGE(X)}
8788 @item @emph{Arguments}:
8789 @multitable @columnfractions .15 .70
8790 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8791 @end multitable
8793 @item @emph{Return value}:
8794 The return value is of type @code{INTEGER} and of the default integer
8795 kind.
8797 @item @emph{Example}:
8798 See @code{PRECISION} for an example.
8799 @end table
8803 @node REAL
8804 @section @code{REAL} --- Convert to real type 
8805 @fnindex REAL
8806 @fnindex REALPART
8807 @cindex conversion, to real
8808 @cindex complex numbers, real part
8810 @table @asis
8811 @item @emph{Description}:
8812 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type.  The
8813 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8814 and its use is strongly discouraged.
8816 @item @emph{Standard}:
8817 Fortran 77 and later
8819 @item @emph{Class}:
8820 Elemental function
8822 @item @emph{Syntax}:
8823 @multitable @columnfractions .80
8824 @item @code{RESULT = REAL(X [, KIND])}
8825 @item @code{RESULT = REALPART(Z)}
8826 @end multitable
8828 @item @emph{Arguments}:
8829 @multitable @columnfractions .15 .70
8830 @item @var{X}    @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
8831                       @code{COMPLEX(*)}.
8832 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
8833                       expression indicating the kind parameter of
8834                       the result.
8835 @end multitable
8837 @item @emph{Return value}:
8838 These functions return a @code{REAL(*)} variable or array under
8839 the following rules: 
8841 @table @asis
8842 @item (A)
8843 @code{REAL(X)} is converted to a default real type if @var{X} is an 
8844 integer or real variable.
8845 @item (B)
8846 @code{REAL(X)} is converted to a real type with the kind type parameter
8847 of @var{X} if @var{X} is a complex variable.
8848 @item (C)
8849 @code{REAL(X, KIND)} is converted to a real type with kind type
8850 parameter @var{KIND} if @var{X} is a complex, integer, or real
8851 variable.
8852 @end table
8854 @item @emph{Example}:
8855 @smallexample
8856 program test_real
8857   complex :: x = (1.0, 2.0)
8858   print *, real(x), real(x,8), realpart(x)
8859 end program test_real
8860 @end smallexample
8862 @item @emph{See also}:
8863 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8865 @end table
8869 @node RENAME
8870 @section @code{RENAME} --- Rename a file
8871 @fnindex RENAME
8872 @cindex file system, rename file
8874 @table @asis
8875 @item @emph{Description}:
8876 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8877 character (@code{CHAR(0)}) can be used to mark the end of the names in
8878 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8879 names are ignored.  If the @var{STATUS} argument is supplied, it
8880 contains 0 on success or a nonzero error code upon return; see
8881 @code{rename(2)}.
8883 This intrinsic is provided in both subroutine and function forms;
8884 however, only one form can be used in any given program unit.
8886 @item @emph{Standard}:
8887 GNU extension
8889 @item @emph{Class}:
8890 Subroutine, function
8892 @item @emph{Syntax}:
8893 @multitable @columnfractions .80
8894 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8895 @item @code{STATUS = RENAME(PATH1, PATH2)}
8896 @end multitable
8898 @item @emph{Arguments}:
8899 @multitable @columnfractions .15 .70
8900 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8901 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8902 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8903 @end multitable
8905 @item @emph{See also}:
8906 @ref{LINK}
8908 @end table
8912 @node REPEAT
8913 @section @code{REPEAT} --- Repeated string concatenation 
8914 @fnindex REPEAT
8915 @cindex string, repeat
8916 @cindex string, concatenate
8918 @table @asis
8919 @item @emph{Description}:
8920 Concatenates @var{NCOPIES} copies of a string.
8922 @item @emph{Standard}:
8923 Fortran 95 and later
8925 @item @emph{Class}:
8926 Transformational function
8928 @item @emph{Syntax}:
8929 @code{RESULT = REPEAT(STRING, NCOPIES)}
8931 @item @emph{Arguments}:
8932 @multitable @columnfractions .15 .70
8933 @item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER(*)}.
8934 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
8935 @end multitable
8937 @item @emph{Return value}:
8938 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies 
8939 of @var{STRING}.
8941 @item @emph{Example}:
8942 @smallexample
8943 program test_repeat
8944   write(*,*) repeat("x", 5)   ! "xxxxx"
8945 end program
8946 @end smallexample
8947 @end table
8951 @node RESHAPE
8952 @section @code{RESHAPE} --- Function to reshape an array
8953 @fnindex RESHAPE
8954 @cindex array, change dimensions
8955 @cindex array, transmogrify
8957 @table @asis
8958 @item @emph{Description}:
8959 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
8960 the new array may be padded with elements from @var{PAD} or permuted
8961 as defined by @var{ORDER}.
8963 @item @emph{Standard}:
8964 Fortran 95 and later
8966 @item @emph{Class}:
8967 Transformational function
8969 @item @emph{Syntax}:
8970 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
8972 @item @emph{Arguments}:
8973 @multitable @columnfractions .15 .70
8974 @item @var{SOURCE} @tab Shall be an array of any type.
8975 @item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an 
8976 array of rank one. Its values must be positive or zero.
8977 @item @var{PAD}    @tab (Optional) shall be an array of the same 
8978 type as @var{SOURCE}.
8979 @item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
8980 and an array of the same shape as @var{SHAPE}. Its values shall
8981 be a permutation of the numbers from 1 to n, where n is the size of 
8982 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
8983 be assumed.
8984 @end multitable
8986 @item @emph{Return value}:
8987 The result is an array of shape @var{SHAPE} with the same type as 
8988 @var{SOURCE}. 
8990 @item @emph{Example}:
8991 @smallexample
8992 PROGRAM test_reshape
8993   INTEGER, DIMENSION(4) :: x
8994   WRITE(*,*) SHAPE(x)                       ! prints "4"
8995   WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
8996 END PROGRAM
8997 @end smallexample
8999 @item @emph{See also}:
9000 @ref{SHAPE}
9001 @end table
9005 @node RRSPACING
9006 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9007 @fnindex RRSPACING
9008 @cindex real number, relative spacing
9009 @cindex floating point, relative spacing
9012 @table @asis
9013 @item @emph{Description}:
9014 @code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
9015 model numbers near @var{X}.
9017 @item @emph{Standard}:
9018 Fortran 95 and later
9020 @item @emph{Class}:
9021 Elemental function
9023 @item @emph{Syntax}:
9024 @code{RESULT = RRSPACING(X)}
9026 @item @emph{Arguments}:
9027 @multitable @columnfractions .15 .70
9028 @item @var{X} @tab Shall be of type @code{REAL}.
9029 @end multitable
9031 @item @emph{Return value}:
9032 The return value is of the same type and kind as @var{X}.
9033 The value returned is equal to
9034 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9036 @item @emph{See also}:
9037 @ref{SPACING}
9038 @end table
9042 @node RSHIFT
9043 @section @code{RSHIFT} --- Right shift bits
9044 @fnindex RSHIFT
9045 @cindex bits, shift right
9047 @table @asis
9048 @item @emph{Description}:
9049 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9050 bits shifted right by @var{SHIFT} places.  If the absolute value of
9051 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 
9052 Bits shifted out from the left end are lost; zeros are shifted in from
9053 the opposite end.
9055 This function has been superseded by the @code{ISHFT} intrinsic, which
9056 is standard in Fortran 95 and later.
9058 @item @emph{Standard}:
9059 GNU extension
9061 @item @emph{Class}:
9062 Elemental function
9064 @item @emph{Syntax}:
9065 @code{RESULT = RSHIFT(I, SHIFT)}
9067 @item @emph{Arguments}:
9068 @multitable @columnfractions .15 .70
9069 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
9070 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
9071 @end multitable
9073 @item @emph{Return value}:
9074 The return value is of type @code{INTEGER(*)} and of the same kind as
9075 @var{I}.
9077 @item @emph{See also}:
9078 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9080 @end table
9084 @node SCALE
9085 @section @code{SCALE} --- Scale a real value
9086 @fnindex SCALE
9087 @cindex real number, scale
9088 @cindex floating point, scale
9090 @table @asis
9091 @item @emph{Description}:
9092 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9094 @item @emph{Standard}:
9095 Fortran 95 and later
9097 @item @emph{Class}:
9098 Elemental function
9100 @item @emph{Syntax}:
9101 @code{RESULT = SCALE(X, I)}
9103 @item @emph{Arguments}:
9104 @multitable @columnfractions .15 .70
9105 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9106 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9107 @end multitable
9109 @item @emph{Return value}:
9110 The return value is of the same type and kind as @var{X}.
9111 Its value is @code{X * RADIX(X)**I}.
9113 @item @emph{Example}:
9114 @smallexample
9115 program test_scale
9116   real :: x = 178.1387e-4
9117   integer :: i = 5
9118   print *, scale(x,i), x*radix(x)**i
9119 end program test_scale
9120 @end smallexample
9122 @end table
9126 @node SCAN
9127 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9128 @fnindex SCAN
9129 @cindex string, find subset
9131 @table @asis
9132 @item @emph{Description}:
9133 Scans a @var{STRING} for any of the characters in a @var{SET} 
9134 of characters.
9136 If @var{BACK} is either absent or equals @code{FALSE}, this function
9137 returns the position of the leftmost character of @var{STRING} that is
9138 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9139 is returned. If no character of @var{SET} is found in @var{STRING}, the 
9140 result is zero.
9142 @item @emph{Standard}:
9143 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9145 @item @emph{Class}:
9146 Elemental function
9148 @item @emph{Syntax}:
9149 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9151 @item @emph{Arguments}:
9152 @multitable @columnfractions .15 .70
9153 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
9154 @item @var{SET}    @tab Shall be of type @code{CHARACTER(*)}.
9155 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
9156 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
9157                         expression indicating the kind parameter of
9158                       the result.
9159 @end multitable
9161 @item @emph{Return value}:
9162 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9163 @var{KIND} is absent, the return value is of default integer kind.
9165 @item @emph{Example}:
9166 @smallexample
9167 PROGRAM test_scan
9168   WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
9169   WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
9170   WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
9171 END PROGRAM
9172 @end smallexample
9174 @item @emph{See also}:
9175 @ref{INDEX intrinsic}, @ref{VERIFY}
9176 @end table
9180 @node SECNDS
9181 @section @code{SECNDS} --- Time function
9182 @fnindex SECNDS
9183 @cindex time, elapsed
9184 @cindex elapsed time
9186 @table @asis
9187 @item @emph{Description}:
9188 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9189 @var{X} is a reference time, also in seconds. If this is zero, the time in
9190 seconds from midnight is returned. This function is non-standard and its
9191 use is discouraged.
9193 @item @emph{Standard}:
9194 GNU extension
9196 @item @emph{Class}:
9197 Function
9199 @item @emph{Syntax}:
9200 @code{RESULT = SECNDS (X)}
9202 @item @emph{Arguments}:
9203 @multitable @columnfractions .15 .70
9204 @item @var{T}     @tab Shall be of type @code{REAL(4)}.
9205 @item @var{X}     @tab Shall be of type @code{REAL(4)}.
9206 @end multitable
9208 @item @emph{Return value}:
9209 None
9211 @item @emph{Example}:
9212 @smallexample
9213 program test_secnds
9214     integer :: i
9215     real(4) :: t1, t2
9216     print *, secnds (0.0)   ! seconds since midnight
9217     t1 = secnds (0.0)       ! reference time
9218     do i = 1, 10000000      ! do something
9219     end do
9220     t2 = secnds (t1)        ! elapsed time
9221     print *, "Something took ", t2, " seconds."
9222 end program test_secnds
9223 @end smallexample
9224 @end table
9228 @node SECOND
9229 @section @code{SECOND} --- CPU time function
9230 @fnindex SECOND
9231 @cindex time, elapsed
9232 @cindex elapsed time
9234 @table @asis
9235 @item @emph{Description}:
9236 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9237 seconds.  This provides the same functionality as the standard
9238 @code{CPU_TIME} intrinsic, and is only included for backwards
9239 compatibility.
9241 This intrinsic is provided in both subroutine and function forms;
9242 however, only one form can be used in any given program unit.
9244 @item @emph{Standard}:
9245 GNU extension
9247 @item @emph{Class}:
9248 Subroutine, function
9250 @item @emph{Syntax}:
9251 @multitable @columnfractions .80
9252 @item @code{CALL SECOND(TIME)}
9253 @item @code{TIME = SECOND()}
9254 @end multitable
9256 @item @emph{Arguments}:
9257 @multitable @columnfractions .15 .70
9258 @item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
9259 @end multitable
9261 @item @emph{Return value}:
9262 In either syntax, @var{TIME} is set to the process's current runtime in
9263 seconds.
9265 @item @emph{See also}:
9266 @ref{CPU_TIME}
9268 @end table
9272 @node SELECTED_CHAR_KIND
9273 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9274 @fnindex SELECTED_CHAR_KIND
9275 @cindex character kind
9276 @cindex kind, character
9278 @table @asis
9279 @item @emph{Description}:
9281 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9282 set named @var{NAME}, if a character set with such a name is supported,
9283 or @math{-1} otherwise. Currently, supported character sets include
9284 ``ASCII'' and ``DEFAULT'', which are equivalent.
9286 @item @emph{Standard}:
9287 Fortran 2003 and later
9289 @item @emph{Class}:
9290 Transformational function
9292 @item @emph{Syntax}:
9293 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9295 @item @emph{Arguments}:
9296 @multitable @columnfractions .15 .70
9297 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9298 @end multitable
9300 @item @emph{Example}:
9301 @smallexample
9302 program ascii_kind
9303   integer,parameter :: ascii = selected_char_kind("ascii")
9304   character(kind=ascii, len=26) :: s
9306   s = ascii_"abcdefghijklmnopqrstuvwxyz"
9307   print *, s
9308 end program ascii_kind
9309 @end smallexample
9310 @end table
9314 @node SELECTED_INT_KIND
9315 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9316 @fnindex SELECTED_INT_KIND
9317 @cindex integer kind
9318 @cindex kind, integer
9320 @table @asis
9321 @item @emph{Description}:
9322 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
9323 type that can represent all values ranging from @math{-10^I} (exclusive)
9324 to @math{10^I} (exclusive). If there is no integer kind that accommodates
9325 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9327 @item @emph{Standard}:
9328 Fortran 95 and later
9330 @item @emph{Class}:
9331 Transformational function
9333 @item @emph{Syntax}:
9334 @code{RESULT = SELECTED_INT_KIND(I)}
9336 @item @emph{Arguments}:
9337 @multitable @columnfractions .15 .70
9338 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
9339 @end multitable
9341 @item @emph{Example}:
9342 @smallexample
9343 program large_integers
9344   integer,parameter :: k5 = selected_int_kind(5)
9345   integer,parameter :: k15 = selected_int_kind(15)
9346   integer(kind=k5) :: i5
9347   integer(kind=k15) :: i15
9349   print *, huge(i5), huge(i15)
9351   ! The following inequalities are always true
9352   print *, huge(i5) >= 10_k5**5-1
9353   print *, huge(i15) >= 10_k15**15-1
9354 end program large_integers
9355 @end smallexample
9356 @end table
9360 @node SELECTED_REAL_KIND
9361 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9362 @fnindex SELECTED_REAL_KIND
9363 @cindex real kind
9364 @cindex kind, real
9366 @table @asis
9367 @item @emph{Description}:
9368 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
9369 with decimal precision greater of at least @code{P} digits and exponent
9370 range greater at least @code{R}. 
9372 @item @emph{Standard}:
9373 Fortran 95 and later
9375 @item @emph{Class}:
9376 Transformational function
9378 @item @emph{Syntax}:
9379 @code{RESULT = SELECTED_REAL_KIND(P, R)}
9381 @item @emph{Arguments}:
9382 @multitable @columnfractions .15 .70
9383 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9384 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9385 @end multitable
9386 At least one argument shall be present.
9388 @item @emph{Return value}:
9390 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9391 a real data type with decimal precision of at least @code{P} digits and a
9392 decimal exponent range of at least @code{R}. If more than one real data
9393 type meet the criteria, the kind of the data type with the smallest
9394 decimal precision is returned. If no real data type matches the criteria,
9395 the result is
9396 @table @asis
9397 @item -1 if the processor does not support a real data type with a
9398 precision greater than or equal to @code{P}
9399 @item -2 if the processor does not support a real type with an exponent
9400 range greater than or equal to @code{R}
9401 @item -3 if neither is supported.
9402 @end table
9404 @item @emph{Example}:
9405 @smallexample
9406 program real_kinds
9407   integer,parameter :: p6 = selected_real_kind(6)
9408   integer,parameter :: p10r100 = selected_real_kind(10,100)
9409   integer,parameter :: r400 = selected_real_kind(r=400)
9410   real(kind=p6) :: x
9411   real(kind=p10r100) :: y
9412   real(kind=r400) :: z
9414   print *, precision(x), range(x)
9415   print *, precision(y), range(y)
9416   print *, precision(z), range(z)
9417 end program real_kinds
9418 @end smallexample
9419 @end table
9423 @node SET_EXPONENT
9424 @section @code{SET_EXPONENT} --- Set the exponent of the model
9425 @fnindex SET_EXPONENT
9426 @cindex real number, set exponent
9427 @cindex floating point, set exponent
9429 @table @asis
9430 @item @emph{Description}:
9431 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9432 is that that of @var{X} and whose exponent part is @var{I}.
9434 @item @emph{Standard}:
9435 Fortran 95 and later
9437 @item @emph{Class}:
9438 Elemental function
9440 @item @emph{Syntax}:
9441 @code{RESULT = SET_EXPONENT(X, I)}
9443 @item @emph{Arguments}:
9444 @multitable @columnfractions .15 .70
9445 @item @var{X} @tab Shall be of type @code{REAL}.
9446 @item @var{I} @tab Shall be of type @code{INTEGER}.
9447 @end multitable
9449 @item @emph{Return value}:
9450 The return value is of the same type and kind as @var{X}.
9451 The real number whose fractional part
9452 is that that of @var{X} and whose exponent part if @var{I} is returned;
9453 it is @code{FRACTION(X) * RADIX(X)**I}.
9455 @item @emph{Example}:
9456 @smallexample
9457 PROGRAM test_setexp
9458   REAL :: x = 178.1387e-4
9459   INTEGER :: i = 17
9460   PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9461 END PROGRAM
9462 @end smallexample
9464 @end table
9468 @node SHAPE
9469 @section @code{SHAPE} --- Determine the shape of an array
9470 @fnindex SHAPE
9471 @cindex array, shape
9473 @table @asis
9474 @item @emph{Description}:
9475 Determines the shape of an array.
9477 @item @emph{Standard}:
9478 Fortran 95 and later
9480 @item @emph{Class}:
9481 Inquiry function
9483 @item @emph{Syntax}:
9484 @code{RESULT = SHAPE(SOURCE)}
9486 @item @emph{Arguments}:
9487 @multitable @columnfractions .15 .70
9488 @item @var{SOURCE} @tab Shall be an array or scalar of any type. 
9489 If @var{SOURCE} is a pointer it must be associated and allocatable 
9490 arrays must be allocated.
9491 @end multitable
9493 @item @emph{Return value}:
9494 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} 
9495 has dimensions. The elements of the resulting array correspond to the extend
9496 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9497 the result is the rank one array of size zero.
9499 @item @emph{Example}:
9500 @smallexample
9501 PROGRAM test_shape
9502   INTEGER, DIMENSION(-1:1, -1:2) :: A
9503   WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
9504   WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
9505 END PROGRAM
9506 @end smallexample
9508 @item @emph{See also}:
9509 @ref{RESHAPE}, @ref{SIZE}
9510 @end table
9514 @node SIGN
9515 @section @code{SIGN} --- Sign copying function
9516 @fnindex SIGN
9517 @fnindex ISIGN
9518 @fnindex DSIGN
9519 @cindex sign copying
9521 @table @asis
9522 @item @emph{Description}:
9523 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9525 @item @emph{Standard}:
9526 Fortran 77 and later
9528 @item @emph{Class}:
9529 Elemental function
9531 @item @emph{Syntax}:
9532 @code{RESULT = SIGN(A, B)}
9534 @item @emph{Arguments}:
9535 @multitable @columnfractions .15 .70
9536 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9537 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9538 @end multitable
9540 @item @emph{Return value}:
9541 The kind of the return value is that of @var{A} and @var{B}.
9542 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9543 it is @code{-ABS(A)}.
9545 @item @emph{Example}:
9546 @smallexample
9547 program test_sign
9548   print *, sign(-12,1)
9549   print *, sign(-12,0)
9550   print *, sign(-12,-1)
9552   print *, sign(-12.,1.)
9553   print *, sign(-12.,0.)
9554   print *, sign(-12.,-1.)
9555 end program test_sign
9556 @end smallexample
9558 @item @emph{Specific names}:
9559 @multitable @columnfractions .20 .20 .20 .25
9560 @item Name              @tab Arguments      @tab Return type    @tab Standard
9561 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9562 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9563 @end multitable
9564 @end table
9568 @node SIGNAL
9569 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9570 @fnindex SIGNAL
9571 @cindex system, signal handling
9573 @table @asis
9574 @item @emph{Description}:
9575 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9576 @var{HANDLER} to be executed with a single integer argument when signal
9577 @var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
9578 turn off handling of signal @var{NUMBER} or revert to its default
9579 action.  See @code{signal(2)}.
9581 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9582 is supplied, it is set to the value returned by @code{signal(2)}.
9584 @item @emph{Standard}:
9585 GNU extension
9587 @item @emph{Class}:
9588 Subroutine, function
9590 @item @emph{Syntax}:
9591 @multitable @columnfractions .80
9592 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9593 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9594 @end multitable
9596 @item @emph{Arguments}:
9597 @multitable @columnfractions .15 .70
9598 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9599 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9600 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9601 @code{INTEGER}. It is @code{INTENT(IN)}.
9602 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9603 integer. It has @code{INTENT(OUT)}.
9604 @end multitable
9606 @item @emph{Return value}:
9607 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9609 @item @emph{Example}:
9610 @smallexample
9611 program test_signal
9612   intrinsic signal
9613   external handler_print
9615   call signal (12, handler_print)
9616   call signal (10, 1)
9618   call sleep (30)
9619 end program test_signal
9620 @end smallexample
9621 @end table
9625 @node SIN
9626 @section @code{SIN} --- Sine function 
9627 @fnindex SIN
9628 @fnindex DSIN
9629 @fnindex CSIN
9630 @fnindex ZSIN
9631 @fnindex CDSIN
9632 @cindex trigonometric function, sine
9633 @cindex sine
9635 @table @asis
9636 @item @emph{Description}:
9637 @code{SIN(X)} computes the sine of @var{X}.
9639 @item @emph{Standard}:
9640 Fortran 77 and later
9642 @item @emph{Class}:
9643 Elemental function
9645 @item @emph{Syntax}:
9646 @code{RESULT = SIN(X)}
9648 @item @emph{Arguments}:
9649 @multitable @columnfractions .15 .70
9650 @item @var{X} @tab The type shall be @code{REAL(*)} or
9651 @code{COMPLEX(*)}.
9652 @end multitable
9654 @item @emph{Return value}:
9655 The return value has same type and kind as @var{X}.
9657 @item @emph{Example}:
9658 @smallexample
9659 program test_sin
9660   real :: x = 0.0
9661   x = sin(x)
9662 end program test_sin
9663 @end smallexample
9665 @item @emph{Specific names}:
9666 @multitable @columnfractions .20 .20 .20 .25
9667 @item Name            @tab Argument          @tab Return type       @tab Standard
9668 @item @code{DSIN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
9669 @item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
9670 @item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
9671 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
9672 @end multitable
9674 @item @emph{See also}:
9675 @ref{ASIN}
9676 @end table
9680 @node SINH
9681 @section @code{SINH} --- Hyperbolic sine function 
9682 @fnindex SINH
9683 @fnindex DSINH
9684 @cindex hyperbolic sine
9685 @cindex hyperbolic function, sine
9686 @cindex sine, hyperbolic
9688 @table @asis
9689 @item @emph{Description}:
9690 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9692 @item @emph{Standard}:
9693 Fortran 95 and later
9695 @item @emph{Class}:
9696 Elemental function
9698 @item @emph{Syntax}:
9699 @code{RESULT = SINH(X)}
9701 @item @emph{Arguments}:
9702 @multitable @columnfractions .15 .70
9703 @item @var{X} @tab The type shall be @code{REAL(*)}.
9704 @end multitable
9706 @item @emph{Return value}:
9707 The return value is of type @code{REAL(*)}.
9709 @item @emph{Example}:
9710 @smallexample
9711 program test_sinh
9712   real(8) :: x = - 1.0_8
9713   x = sinh(x)
9714 end program test_sinh
9715 @end smallexample
9717 @item @emph{Specific names}:
9718 @multitable @columnfractions .20 .20 .20 .25
9719 @item Name            @tab Argument          @tab Return type       @tab Standard
9720 @item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
9721 @end multitable
9723 @item @emph{See also}:
9724 @ref{ASINH}
9725 @end table
9729 @node SIZE
9730 @section @code{SIZE} --- Determine the size of an array
9731 @fnindex SIZE
9732 @cindex array, size
9733 @cindex array, number of elements
9734 @cindex array, count elements
9736 @table @asis
9737 @item @emph{Description}:
9738 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9739 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9741 @item @emph{Standard}:
9742 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9744 @item @emph{Class}:
9745 Inquiry function
9747 @item @emph{Syntax}:
9748 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9750 @item @emph{Arguments}:
9751 @multitable @columnfractions .15 .70
9752 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9753 a pointer it must be associated and allocatable arrays must be allocated.
9754 @item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER} 
9755 and its value shall be in the range from 1 to n, where n equals the rank 
9756 of @var{ARRAY}.
9757 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9758                       expression indicating the kind parameter of
9759                       the result.
9760 @end multitable
9762 @item @emph{Return value}:
9763 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9764 @var{KIND} is absent, the return value is of default integer kind.
9766 @item @emph{Example}:
9767 @smallexample
9768 PROGRAM test_size
9769   WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
9770 END PROGRAM
9771 @end smallexample
9773 @item @emph{See also}:
9774 @ref{SHAPE}, @ref{RESHAPE}
9775 @end table
9778 @node SIZEOF
9779 @section @code{SIZEOF} --- Size in bytes of an expression
9780 @fnindex SIZEOF
9781 @cindex expression size
9782 @cindex size of an expression
9784 @table @asis
9785 @item @emph{Description}:
9786 @code{SIZEOF(X)} calculates the number of bytes of storage the
9787 expression @code{X} occupies.
9789 @item @emph{Standard}:
9790 GNU extension
9792 @item @emph{Class}:
9793 Intrinsic function
9795 @item @emph{Syntax}:
9796 @code{N = SIZEOF(X)}
9798 @item @emph{Arguments}:
9799 @multitable @columnfractions .15 .70
9800 @item @var{X} @tab The argument shall be of any type, rank or shape.
9801 @end multitable
9803 @item @emph{Return value}:
9804 The return value is of type integer and of the system-dependent kind
9805 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9806 number of bytes occupied by the argument.  If the argument has the
9807 @code{POINTER} attribute, the number of bytes of the storage area pointed
9808 to is returned.  If the argument is of a derived type with @code{POINTER}
9809 or @code{ALLOCATABLE} components, the return value doesn't account for
9810 the sizes of the data pointed to by these components.
9812 @item @emph{Example}:
9813 @smallexample
9814    integer :: i
9815    real :: r, s(5)
9816    print *, (sizeof(s)/sizeof(r) == 5)
9817    end
9818 @end smallexample
9819 The example will print @code{.TRUE.} unless you are using a platform
9820 where default @code{REAL} variables are unusually padded.
9821 @end table
9823 @node SLEEP
9824 @section @code{SLEEP} --- Sleep for the specified number of seconds
9825 @fnindex SLEEP
9826 @cindex delayed execution
9828 @table @asis
9829 @item @emph{Description}:
9830 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9832 @item @emph{Standard}:
9833 GNU extension
9835 @item @emph{Class}:
9836 Subroutine
9838 @item @emph{Syntax}:
9839 @code{CALL SLEEP(SECONDS)}
9841 @item @emph{Arguments}:
9842 @multitable @columnfractions .15 .70
9843 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9844 @end multitable
9846 @item @emph{Example}:
9847 @smallexample
9848 program test_sleep
9849   call sleep(5)
9851 @end smallexample
9852 @end table
9856 @node SNGL
9857 @section @code{SNGL} --- Convert double precision real to default real
9858 @fnindex SNGL
9859 @cindex conversion, to real
9861 @table @asis
9862 @item @emph{Description}:
9863 @code{SNGL(A)} converts the double precision real @var{A}
9864 to a default real value. This is an archaic form of @code{REAL}
9865 that is specific to one type for @var{A}.
9867 @item @emph{Standard}:
9868 Fortran 77 and later
9870 @item @emph{Class}:
9871 Elemental function
9873 @item @emph{Syntax}:
9874 @code{RESULT = SNGL(A)}
9876 @item @emph{Arguments}:
9877 @multitable @columnfractions .15 .70
9878 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9879 @end multitable
9881 @item @emph{Return value}:
9882 The return value is of type default @code{REAL}.
9884 @item @emph{See also}:
9885 @ref{DBLE}
9886 @end table
9890 @node SPACING
9891 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9892 @fnindex SPACING
9893 @cindex real number, relative spacing
9894 @cindex floating point, relative spacing
9896 @table @asis
9897 @item @emph{Description}:
9898 Determines the distance between the argument @var{X} and the nearest 
9899 adjacent number of the same type.
9901 @item @emph{Standard}:
9902 Fortran 95 and later
9904 @item @emph{Class}:
9905 Elemental function
9907 @item @emph{Syntax}:
9908 @code{RESULT = SPACING(X)}
9910 @item @emph{Arguments}:
9911 @multitable @columnfractions .15 .70
9912 @item @var{X} @tab Shall be of type @code{REAL(*)}.
9913 @end multitable
9915 @item @emph{Return value}:
9916 The result is of the same type as the input argument @var{X}.
9918 @item @emph{Example}:
9919 @smallexample
9920 PROGRAM test_spacing
9921   INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9922   INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9924   WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
9925   WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
9926 END PROGRAM
9927 @end smallexample
9929 @item @emph{See also}:
9930 @ref{RRSPACING}
9931 @end table
9935 @node SPREAD
9936 @section @code{SPREAD} --- Add a dimension to an array
9937 @fnindex SPREAD
9938 @cindex array, increase dimension
9939 @cindex array, duplicate elements
9940 @cindex array, duplicate dimensions
9942 @table @asis
9943 @item @emph{Description}:
9944 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified 
9945 dimension @var{DIM}.
9947 @item @emph{Standard}:
9948 Fortran 95 and later
9950 @item @emph{Class}:
9951 Transformational function
9953 @item @emph{Syntax}:
9954 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
9956 @item @emph{Arguments}:
9957 @multitable @columnfractions .15 .70
9958 @item @var{SOURCE}  @tab Shall be a scalar or an array of any type and 
9959 a rank less than seven.
9960 @item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a 
9961 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
9962 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
9963 @end multitable
9965 @item @emph{Return value}:
9966 The result is an array of the same type as @var{SOURCE} and has rank n+1
9967 where n equals the rank of @var{SOURCE}.
9969 @item @emph{Example}:
9970 @smallexample
9971 PROGRAM test_spread
9972   INTEGER :: a = 1, b(2) = (/ 1, 2 /)
9973   WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
9974   WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
9975 END PROGRAM
9976 @end smallexample
9978 @item @emph{See also}:
9979 @ref{UNPACK}
9980 @end table
9984 @node SQRT
9985 @section @code{SQRT} --- Square-root function
9986 @fnindex SQRT
9987 @fnindex DSQRT
9988 @fnindex CSQRT
9989 @fnindex ZSQRT
9990 @fnindex CDSQRT
9991 @cindex root
9992 @cindex square-root
9994 @table @asis
9995 @item @emph{Description}:
9996 @code{SQRT(X)} computes the square root of @var{X}.
9998 @item @emph{Standard}:
9999 Fortran 77 and later
10001 @item @emph{Class}:
10002 Elemental function
10004 @item @emph{Syntax}:
10005 @code{RESULT = SQRT(X)}
10007 @item @emph{Arguments}:
10008 @multitable @columnfractions .15 .70
10009 @item @var{X} @tab The type shall be @code{REAL(*)} or
10010 @code{COMPLEX(*)}.
10011 @end multitable
10013 @item @emph{Return value}:
10014 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
10015 The kind type parameter is the same as @var{X}.
10017 @item @emph{Example}:
10018 @smallexample
10019 program test_sqrt
10020   real(8) :: x = 2.0_8
10021   complex :: z = (1.0, 2.0)
10022   x = sqrt(x)
10023   z = sqrt(z)
10024 end program test_sqrt
10025 @end smallexample
10027 @item @emph{Specific names}:
10028 @multitable @columnfractions .20 .20 .20 .25
10029 @item Name             @tab Argument             @tab Return type          @tab Standard
10030 @item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab Fortran 95 and later
10031 @item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 95 and later
10032 @item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
10033 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
10034 @end multitable
10035 @end table
10039 @node SRAND
10040 @section @code{SRAND} --- Reinitialize the random number generator
10041 @fnindex SRAND
10042 @cindex random number generation, seeding
10043 @cindex seeding a random number generator
10045 @table @asis
10046 @item @emph{Description}:
10047 @code{SRAND} reinitializes the pseudo-random number generator
10048 called by @code{RAND} and @code{IRAND}. The new seed used by the
10049 generator is specified by the required argument @var{SEED}.
10051 @item @emph{Standard}:
10052 GNU extension
10054 @item @emph{Class}:
10055 Subroutine
10057 @item @emph{Syntax}:
10058 @code{CALL SRAND(SEED)}
10060 @item @emph{Arguments}:
10061 @multitable @columnfractions .15 .70
10062 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10063 @end multitable
10065 @item @emph{Return value}:
10066 Does not return.
10068 @item @emph{Example}:
10069 See @code{RAND} and @code{IRAND} for examples.
10071 @item @emph{Notes}:
10072 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10073 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10074 to generate pseudo-random numbers. Please note that in
10075 GNU Fortran, these two sets of intrinsics (@code{RAND},
10076 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10077 @code{RANDOM_SEED} on the other hand) access two independent
10078 pseudo-random number generators.
10080 @item @emph{See also}:
10081 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10083 @end table
10087 @node STAT
10088 @section @code{STAT} --- Get file status
10089 @fnindex STAT
10090 @cindex file system, file status
10092 @table @asis
10093 @item @emph{Description}:
10094 This function returns information about a file. No permissions are required on 
10095 the file itself, but execute (search) permission is required on all of the 
10096 directories in path that lead to the file.
10098 The elements that are obtained and stored in the array @code{BUFF}:
10099 @multitable @columnfractions .15 .70
10100 @item @code{buff(1)}   @tab  Device ID 
10101 @item @code{buff(2)}   @tab  Inode number 
10102 @item @code{buff(3)}   @tab  File mode 
10103 @item @code{buff(4)}   @tab  Number of links 
10104 @item @code{buff(5)}   @tab  Owner's uid 
10105 @item @code{buff(6)}   @tab  Owner's gid 
10106 @item @code{buff(7)}   @tab  ID of device containing directory entry for file (0 if not available) 
10107 @item @code{buff(8)}   @tab  File size (bytes) 
10108 @item @code{buff(9)}   @tab  Last access time 
10109 @item @code{buff(10)}  @tab  Last modification time 
10110 @item @code{buff(11)}  @tab  Last file status change time 
10111 @item @code{buff(12)}  @tab  Preferred I/O block size (-1 if not available) 
10112 @item @code{buff(13)}  @tab  Number of blocks allocated (-1 if not available)
10113 @end multitable
10115 Not all these elements are relevant on all systems. 
10116 If an element is not relevant, it is returned as 0.
10118 This intrinsic is provided in both subroutine and function forms; however,
10119 only one form can be used in any given program unit.
10121 @item @emph{Standard}:
10122 GNU extension
10124 @item @emph{Class}:
10125 Subroutine, function
10127 @item @emph{Syntax}:
10128 @code{CALL STAT(FILE,BUFF[,STATUS])}
10130 @item @emph{Arguments}:
10131 @multitable @columnfractions .15 .70
10132 @item @var{FILE}   @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
10133 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10134 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 
10135                         on success and a system specific error code otherwise.
10136 @end multitable
10138 @item @emph{Example}:
10139 @smallexample
10140 PROGRAM test_stat
10141   INTEGER, DIMENSION(13) :: buff
10142   INTEGER :: status
10144   CALL STAT("/etc/passwd", buff, status)
10146   IF (status == 0) THEN
10147     WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
10148     WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
10149     WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
10150     WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
10151     WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
10152     WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
10153     WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
10154     WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
10155     WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
10156     WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
10157     WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10158     WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
10159     WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10160   END IF
10161 END PROGRAM
10162 @end smallexample
10164 @item @emph{See also}:
10165 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10166 @end table
10170 @node SUM
10171 @section @code{SUM} --- Sum of array elements
10172 @fnindex SUM
10173 @cindex array, sum
10174 @cindex array, add elements
10175 @cindex array, conditionally add elements
10176 @cindex sum array elements
10178 @table @asis
10179 @item @emph{Description}:
10180 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10181 the corresponding element in @var{MASK} is @code{TRUE}.
10183 @item @emph{Standard}:
10184 Fortran 95 and later
10186 @item @emph{Class}:
10187 Transformational function
10189 @item @emph{Syntax}:
10190 @code{RESULT = SUM(ARRAY[, MASK])}
10191 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10193 @item @emph{Arguments}:
10194 @multitable @columnfractions .15 .70
10195 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)}, 
10196 @code{REAL(*)} or @code{COMPLEX(*)}.
10197 @item @var{DIM}   @tab (Optional) shall be a scalar of type 
10198 @code{INTEGER} with a value in the range from 1 to n, where n 
10199 equals the rank of @var{ARRAY}.
10200 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL} 
10201 and either be a scalar or an array of the same shape as @var{ARRAY}.
10202 @end multitable
10204 @item @emph{Return value}:
10205 The result is of the same type as @var{ARRAY}.
10207 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10208 is returned. Otherwise, an array of rank n-1, where n equals the rank of 
10209 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM} 
10210 dropped is returned.
10212 @item @emph{Example}:
10213 @smallexample
10214 PROGRAM test_sum
10215   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10216   print *, SUM(x)                        ! all elements, sum = 15
10217   print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
10218 END PROGRAM
10219 @end smallexample
10221 @item @emph{See also}:
10222 @ref{PRODUCT}
10223 @end table
10227 @node SYMLNK
10228 @section @code{SYMLNK} --- Create a symbolic link
10229 @fnindex SYMLNK
10230 @cindex file system, create link
10231 @cindex file system, soft link
10233 @table @asis
10234 @item @emph{Description}:
10235 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10236 character (@code{CHAR(0)}) can be used to mark the end of the names in
10237 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10238 names are ignored.  If the @var{STATUS} argument is supplied, it
10239 contains 0 on success or a nonzero error code upon return; see
10240 @code{symlink(2)}.  If the system does not supply @code{symlink(2)}, 
10241 @code{ENOSYS} is returned.
10243 This intrinsic is provided in both subroutine and function forms;
10244 however, only one form can be used in any given program unit.
10246 @item @emph{Standard}:
10247 GNU extension
10249 @item @emph{Class}:
10250 Subroutine, function
10252 @item @emph{Syntax}:
10253 @multitable @columnfractions .80
10254 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10255 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10256 @end multitable
10258 @item @emph{Arguments}:
10259 @multitable @columnfractions .15 .70
10260 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10261 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10262 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10263 @end multitable
10265 @item @emph{See also}:
10266 @ref{LINK}, @ref{UNLINK}
10268 @end table
10272 @node SYSTEM
10273 @section @code{SYSTEM} --- Execute a shell command
10274 @fnindex SYSTEM
10275 @cindex system, system call
10277 @table @asis
10278 @item @emph{Description}:
10279 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10280 argument @var{STATUS} is present, it contains the value returned by
10281 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10282 Note that which shell is used to invoke the command is system-dependent
10283 and environment-dependent.
10285 This intrinsic is provided in both subroutine and function forms;
10286 however, only one form can be used in any given program unit.
10288 @item @emph{Standard}:
10289 GNU extension
10291 @item @emph{Class}:
10292 Subroutine, function
10294 @item @emph{Syntax}:
10295 @multitable @columnfractions .80
10296 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10297 @item @code{STATUS = SYSTEM(COMMAND)}
10298 @end multitable
10300 @item @emph{Arguments}:
10301 @multitable @columnfractions .15 .70
10302 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10303 @item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
10304 @end multitable
10306 @item @emph{See also}:
10307 @end table
10311 @node SYSTEM_CLOCK
10312 @section @code{SYSTEM_CLOCK} --- Time function
10313 @fnindex SYSTEM_CLOCK
10314 @cindex time, clock ticks
10315 @cindex clock ticks
10317 @table @asis
10318 @item @emph{Description}:
10319 Determines the @var{COUNT} of milliseconds of wall clock time since 
10320 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX}, 
10321 @var{COUNT_RATE} determines the number of clock ticks per second.
10322 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to 
10323 @command{gfortran}.
10325 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10326 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero 
10328 @item @emph{Standard}:
10329 Fortran 95 and later
10331 @item @emph{Class}:
10332 Subroutine
10334 @item @emph{Syntax}:
10335 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10337 @item @emph{Arguments}:
10338 @item @emph{Arguments}:
10339 @multitable @columnfractions .15 .70
10340 @item @var{COUNT}      @tab (Optional) shall be a scalar of type default 
10341 @code{INTEGER} with @code{INTENT(OUT)}.
10342 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default 
10343 @code{INTEGER} with @code{INTENT(OUT)}.
10344 @item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type default 
10345 @code{INTEGER} with @code{INTENT(OUT)}.
10346 @end multitable
10348 @item @emph{Example}:
10349 @smallexample
10350 PROGRAM test_system_clock
10351   INTEGER :: count, count_rate, count_max
10352   CALL SYSTEM_CLOCK(count, count_rate, count_max)
10353   WRITE(*,*) count, count_rate, count_max
10354 END PROGRAM
10355 @end smallexample
10357 @item @emph{See also}:
10358 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10359 @end table
10363 @node TAN
10364 @section @code{TAN} --- Tangent function
10365 @fnindex TAN
10366 @fnindex DTAN
10367 @cindex trigonometric function, tangent
10368 @cindex tangent
10370 @table @asis
10371 @item @emph{Description}:
10372 @code{TAN(X)} computes the tangent of @var{X}.
10374 @item @emph{Standard}:
10375 Fortran 77 and later
10377 @item @emph{Class}:
10378 Elemental function
10380 @item @emph{Syntax}:
10381 @code{RESULT = TAN(X)}
10383 @item @emph{Arguments}:
10384 @multitable @columnfractions .15 .70
10385 @item @var{X} @tab The type shall be @code{REAL(*)}.
10386 @end multitable
10388 @item @emph{Return value}:
10389 The return value is of type @code{REAL(*)}.  The kind type parameter is
10390 the same as @var{X}.
10392 @item @emph{Example}:
10393 @smallexample
10394 program test_tan
10395   real(8) :: x = 0.165_8
10396   x = tan(x)
10397 end program test_tan
10398 @end smallexample
10400 @item @emph{Specific names}:
10401 @multitable @columnfractions .20 .20 .20 .25
10402 @item Name            @tab Argument          @tab Return type       @tab Standard
10403 @item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
10404 @end multitable
10406 @item @emph{See also}:
10407 @ref{ATAN}
10408 @end table
10412 @node TANH
10413 @section @code{TANH} --- Hyperbolic tangent function 
10414 @fnindex TANH
10415 @fnindex DTANH
10416 @cindex hyperbolic tangent
10417 @cindex hyperbolic function, tangent
10418 @cindex tangent, hyperbolic
10420 @table @asis
10421 @item @emph{Description}:
10422 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10424 @item @emph{Standard}:
10425 Fortran 77 and later
10427 @item @emph{Class}:
10428 Elemental function
10430 @item @emph{Syntax}:
10431 @code{X = TANH(X)}
10433 @item @emph{Arguments}:
10434 @multitable @columnfractions .15 .70
10435 @item @var{X} @tab The type shall be @code{REAL(*)}.
10436 @end multitable
10438 @item @emph{Return value}:
10439 The return value is of type @code{REAL(*)} and lies in the range
10440 @math{ - 1 \leq tanh(x) \leq 1 }.
10442 @item @emph{Example}:
10443 @smallexample
10444 program test_tanh
10445   real(8) :: x = 2.1_8
10446   x = tanh(x)
10447 end program test_tanh
10448 @end smallexample
10450 @item @emph{Specific names}:
10451 @multitable @columnfractions .20 .20 .20 .25
10452 @item Name            @tab Argument          @tab Return type       @tab Standard
10453 @item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
10454 @end multitable
10456 @item @emph{See also}:
10457 @ref{ATANH}
10458 @end table
10462 @node TIME
10463 @section @code{TIME} --- Time function
10464 @fnindex TIME
10465 @cindex time, current
10466 @cindex current time
10468 @table @asis
10469 @item @emph{Description}:
10470 Returns the current time encoded as an integer (in the manner of the
10471 UNIX function @code{time(3)}). This value is suitable for passing to
10472 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10474 This intrinsic is not fully portable, such as to systems with 32-bit
10475 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10476 the values returned by this intrinsic might be, or become, negative, or
10477 numerically less than previous values, during a single run of the
10478 compiled program.
10480 See @ref{TIME8}, for information on a similar intrinsic that might be
10481 portable to more GNU Fortran implementations, though to fewer Fortran
10482 compilers.
10484 @item @emph{Standard}:
10485 GNU extension
10487 @item @emph{Class}:
10488 Function
10490 @item @emph{Syntax}:
10491 @code{RESULT = TIME()}
10493 @item @emph{Return value}:
10494 The return value is a scalar of type @code{INTEGER(4)}.
10496 @item @emph{See also}:
10497 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10499 @end table
10503 @node TIME8
10504 @section @code{TIME8} --- Time function (64-bit)
10505 @fnindex TIME8
10506 @cindex time, current
10507 @cindex current time
10509 @table @asis
10510 @item @emph{Description}:
10511 Returns the current time encoded as an integer (in the manner of the
10512 UNIX function @code{time(3)}). This value is suitable for passing to
10513 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10515 @emph{Warning:} this intrinsic does not increase the range of the timing
10516 values over that returned by @code{time(3)}. On a system with a 32-bit
10517 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10518 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10519 overflows of the 32-bit value can still occur. Therefore, the values
10520 returned by this intrinsic might be or become negative or numerically
10521 less than previous values during a single run of the compiled program.
10523 @item @emph{Standard}:
10524 GNU extension
10526 @item @emph{Class}:
10527 Function
10529 @item @emph{Syntax}:
10530 @code{RESULT = TIME8()}
10532 @item @emph{Return value}:
10533 The return value is a scalar of type @code{INTEGER(8)}.
10535 @item @emph{See also}:
10536 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10538 @end table
10542 @node TINY
10543 @section @code{TINY} --- Smallest positive number of a real kind
10544 @fnindex TINY
10545 @cindex limits, smallest number
10546 @cindex model representation, smallest number
10548 @table @asis
10549 @item @emph{Description}:
10550 @code{TINY(X)} returns the smallest positive (non zero) number
10551 in the model of the type of @code{X}.
10553 @item @emph{Standard}:
10554 Fortran 95 and later
10556 @item @emph{Class}:
10557 Inquiry function
10559 @item @emph{Syntax}:
10560 @code{RESULT = TINY(X)}
10562 @item @emph{Arguments}:
10563 @multitable @columnfractions .15 .70
10564 @item @var{X} @tab Shall be of type @code{REAL}.
10565 @end multitable
10567 @item @emph{Return value}:
10568 The return value is of the same type and kind as @var{X}
10570 @item @emph{Example}:
10571 See @code{HUGE} for an example.
10572 @end table
10576 @node TRANSFER
10577 @section @code{TRANSFER} --- Transfer bit patterns
10578 @fnindex TRANSFER
10579 @cindex bits, move
10580 @cindex type cast
10582 @table @asis
10583 @item @emph{Description}:
10584 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10585 is the representation of a variable or array of the same type and type
10586 parameters as @var{MOLD}.
10588 This is approximately equivalent to the C concept of @emph{casting} one
10589 type to another.
10591 @item @emph{Standard}:
10592 Fortran 95 and later
10594 @item @emph{Class}:
10595 Transformational function
10597 @item @emph{Syntax}:
10598 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10600 @item @emph{Arguments}:
10601 @multitable @columnfractions .15 .70
10602 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10603 @item @var{MOLD}   @tab Shall be a scalar or an array of any type.
10604 @item @var{SIZE}   @tab (Optional) shall be a scalar of type 
10605 @code{INTEGER}.
10606 @end multitable
10608 @item @emph{Return value}:
10609 The result has the same type as @var{MOLD}, with the bit level
10610 representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
10611 a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
10612 but @var{MOLD} is an array (of any size or shape), the result is a one-
10613 dimensional array of the minimum length needed to contain the entirety
10614 of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
10615 and @var{MOLD} is a scalar, the result is a scalar.
10617 If the bitwise representation of the result is longer than that of
10618 @var{SOURCE}, then the leading bits of the result correspond to those of
10619 @var{SOURCE} and any trailing bits are filled arbitrarily.
10621 When the resulting bit representation does not correspond to a valid
10622 representation of a variable of the same type as @var{MOLD}, the results
10623 are undefined, and subsequent operations on the result cannot be
10624 guaranteed to produce sensible behavior.  For example, it is possible to
10625 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10626 @code{.NOT.@var{VAR}} both appear to be true.
10628 @item @emph{Example}:
10629 @smallexample
10630 PROGRAM test_transfer
10631   integer :: x = 2143289344
10632   print *, transfer(x, 1.0)    ! prints "NaN" on i686
10633 END PROGRAM
10634 @end smallexample
10635 @end table
10639 @node TRANSPOSE
10640 @section @code{TRANSPOSE} --- Transpose an array of rank two
10641 @fnindex TRANSPOSE
10642 @cindex array, transpose
10643 @cindex matrix, transpose
10644 @cindex transpose
10646 @table @asis
10647 @item @emph{Description}:
10648 Transpose an array of rank two. Element (i, j) of the result has the value 
10649 @code{MATRIX(j, i)}, for all i, j.
10651 @item @emph{Standard}:
10652 Fortran 95 and later
10654 @item @emph{Class}:
10655 Transformational function
10657 @item @emph{Syntax}:
10658 @code{RESULT = TRANSPOSE(MATRIX)}
10660 @item @emph{Arguments}:
10661 @multitable @columnfractions .15 .70
10662 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10663 @end multitable
10665 @item @emph{Return value}:
10666 The result has the same type as @var{MATRIX}, and has shape 
10667 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10668 @end table
10672 @node TRIM
10673 @section @code{TRIM} --- Remove trailing blank characters of a string
10674 @fnindex TRIM
10675 @cindex string, remove trailing whitespace
10677 @table @asis
10678 @item @emph{Description}:
10679 Removes trailing blank characters of a string.
10681 @item @emph{Standard}:
10682 Fortran 95 and later
10684 @item @emph{Class}:
10685 Transformational function
10687 @item @emph{Syntax}:
10688 @code{RESULT = TRIM(STRING)}
10690 @item @emph{Arguments}:
10691 @multitable @columnfractions .15 .70
10692 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
10693 @end multitable
10695 @item @emph{Return value}:
10696 A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
10697 less the number of trailing blanks.
10699 @item @emph{Example}:
10700 @smallexample
10701 PROGRAM test_trim
10702   CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
10703   WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
10704 END PROGRAM
10705 @end smallexample
10707 @item @emph{See also}:
10708 @ref{ADJUSTL}, @ref{ADJUSTR}
10709 @end table
10713 @node TTYNAM
10714 @section @code{TTYNAM} --- Get the name of a terminal device.
10715 @fnindex TTYNAM
10716 @cindex system, terminal
10718 @table @asis
10719 @item @emph{Description}:
10720 Get the name of a terminal device. For more information, 
10721 see @code{ttyname(3)}.
10723 This intrinsic is provided in both subroutine and function forms; 
10724 however, only one form can be used in any given program unit. 
10726 @item @emph{Standard}:
10727 GNU extension
10729 @item @emph{Class}:
10730 Subroutine, function
10732 @item @emph{Syntax}:
10733 @multitable @columnfractions .80
10734 @item @code{CALL TTYNAM(UNIT, NAME)}
10735 @item @code{NAME = TTYNAM(UNIT)}
10736 @end multitable
10738 @item @emph{Arguments}:
10739 @multitable @columnfractions .15 .70
10740 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
10741 @item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
10742 @end multitable
10744 @item @emph{Example}:
10745 @smallexample
10746 PROGRAM test_ttynam
10747   INTEGER :: unit
10748   DO unit = 1, 10
10749     IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10750   END DO
10751 END PROGRAM
10752 @end smallexample
10754 @item @emph{See also}:
10755 @ref{ISATTY}
10756 @end table
10760 @node UBOUND
10761 @section @code{UBOUND} --- Upper dimension bounds of an array
10762 @fnindex UBOUND
10763 @cindex array, upper bound
10765 @table @asis
10766 @item @emph{Description}:
10767 Returns the upper bounds of an array, or a single upper bound
10768 along the @var{DIM} dimension.
10769 @item @emph{Standard}:
10770 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10772 @item @emph{Class}:
10773 Inquiry function
10775 @item @emph{Syntax}:
10776 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10778 @item @emph{Arguments}:
10779 @multitable @columnfractions .15 .70
10780 @item @var{ARRAY} @tab Shall be an array, of any type.
10781 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
10782 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10783                      expression indicating the kind parameter of
10784                      the result.
10785 @end multitable
10787 @item @emph{Return value}:
10788 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10789 @var{KIND} is absent, the return value is of default integer kind.
10790 If @var{DIM} is absent, the result is an array of the upper bounds of
10791 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
10792 corresponding to the upper bound of the array along that dimension.  If
10793 @var{ARRAY} is an expression rather than a whole array or array
10794 structure component, or if it has a zero extent along the relevant
10795 dimension, the upper bound is taken to be the number of elements along
10796 the relevant dimension.
10798 @item @emph{See also}:
10799 @ref{LBOUND}
10800 @end table
10804 @node UMASK
10805 @section @code{UMASK} --- Set the file creation mask
10806 @fnindex UMASK
10807 @cindex file system, file creation mask
10809 @table @asis
10810 @item @emph{Description}:
10811 Sets the file creation mask to @var{MASK} and returns the old value in
10812 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10814 @item @emph{Standard}:
10815 GNU extension
10817 @item @emph{Class}:
10818 Subroutine
10820 @item @emph{Syntax}:
10821 @code{CALL UMASK(MASK [, OLD])}
10823 @item @emph{Arguments}:
10824 @multitable @columnfractions .15 .70
10825 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
10826 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10827                       @code{INTEGER(*)}.
10828 @end multitable
10830 @end table
10834 @node UNLINK
10835 @section @code{UNLINK} --- Remove a file from the file system
10836 @fnindex UNLINK
10837 @cindex file system, remove file
10839 @table @asis
10840 @item @emph{Description}:
10841 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10842 used to mark the end of the name in @var{PATH}; otherwise, trailing
10843 blanks in the file name are ignored.  If the @var{STATUS} argument is
10844 supplied, it contains 0 on success or a nonzero error code upon return;
10845 see @code{unlink(2)}.
10847 This intrinsic is provided in both subroutine and function forms;
10848 however, only one form can be used in any given program unit.
10850 @item @emph{Standard}:
10851 GNU extension
10853 @item @emph{Class}:
10854 Subroutine, function
10856 @item @emph{Syntax}:
10857 @multitable @columnfractions .80
10858 @item @code{CALL UNLINK(PATH [, STATUS])}
10859 @item @code{STATUS = UNLINK(PATH)}
10860 @end multitable
10862 @item @emph{Arguments}:
10863 @multitable @columnfractions .15 .70
10864 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
10865 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10866 @end multitable
10868 @item @emph{See also}:
10869 @ref{LINK}, @ref{SYMLNK}
10870 @end table
10874 @node UNPACK
10875 @section @code{UNPACK} --- Unpack an array of rank one into an array
10876 @fnindex UNPACK
10877 @cindex array, unpacking
10878 @cindex array, increase dimension
10879 @cindex array, scatter elements
10881 @table @asis
10882 @item @emph{Description}:
10883 Store the elements of @var{VECTOR} in an array of higher rank.
10885 @item @emph{Standard}:
10886 Fortran 95 and later
10888 @item @emph{Class}:
10889 Transformational function
10891 @item @emph{Syntax}:
10892 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10894 @item @emph{Arguments}:
10895 @multitable @columnfractions .15 .70
10896 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It 
10897 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10898 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
10899 @item @var{FIELD}  @tab Shall be of the same type as @var{VECTOR} and have
10900 the same shape as @var{MASK}.
10901 @end multitable
10903 @item @emph{Return value}:
10904 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10905 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10907 @item @emph{Example}:
10908 @smallexample
10909 PROGRAM test_unpack
10910   integer :: vector(2)  = (/1,1/)
10911   logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10912   integer :: field(2,2) = 0, unity(2,2)
10914   ! result: unity matrix
10915   unity = unpack(vector, reshape(mask, (/2,2/)), field)
10916 END PROGRAM
10917 @end smallexample
10919 @item @emph{See also}:
10920 @ref{PACK}, @ref{SPREAD}
10921 @end table
10925 @node VERIFY
10926 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10927 @fnindex VERIFY
10928 @cindex string, find missing set
10930 @table @asis
10931 @item @emph{Description}:
10932 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
10934 If @var{BACK} is either absent or equals @code{FALSE}, this function
10935 returns the position of the leftmost character of @var{STRING} that is
10936 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10937 is returned. If all characters of @var{SET} are found in @var{STRING}, the 
10938 result is zero.
10940 @item @emph{Standard}:
10941 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10943 @item @emph{Class}:
10944 Elemental function
10946 @item @emph{Syntax}:
10947 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
10949 @item @emph{Arguments}:
10950 @multitable @columnfractions .15 .70
10951 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
10952 @item @var{SET}    @tab Shall be of type @code{CHARACTER(*)}.
10953 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
10954 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
10955                         expression indicating the kind parameter of
10956                         the result.
10957 @end multitable
10959 @item @emph{Return value}:
10960 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10961 @var{KIND} is absent, the return value is of default integer kind.
10963 @item @emph{Example}:
10964 @smallexample
10965 PROGRAM test_verify
10966   WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
10967   WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
10968   WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
10969   WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
10970   WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
10971 END PROGRAM
10972 @end smallexample
10974 @item @emph{See also}:
10975 @ref{SCAN}, @ref{INDEX intrinsic}
10976 @end table
10980 @node XOR
10981 @section @code{XOR} --- Bitwise logical exclusive OR
10982 @fnindex XOR
10983 @cindex bitwise logical exclusive or
10984 @cindex logical exclusive or, bitwise
10986 @table @asis
10987 @item @emph{Description}:
10988 Bitwise logical exclusive or. 
10990 This intrinsic routine is provided for backwards compatibility with 
10991 GNU Fortran 77.  For integer arguments, programmers should consider
10992 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
10994 @item @emph{Standard}:
10995 GNU extension
10997 @item @emph{Class}:
10998 Function
11000 @item @emph{Syntax}:
11001 @code{RESULT = XOR(X, Y)}
11003 @item @emph{Arguments}:
11004 @multitable @columnfractions .15 .70
11005 @item @var{X} @tab The type shall be either  a scalar @code{INTEGER(*)}
11006 type or a scalar @code{LOGICAL} type.
11007 @item @var{Y} @tab The type shall be the same as the type of @var{I}.
11008 @end multitable
11010 @item @emph{Return value}:
11011 The return type is either a scalar @code{INTEGER(*)} or a scalar
11012 @code{LOGICAL}.  If the kind type parameters differ, then the
11013 smaller kind type is implicitly converted to larger kind, and the 
11014 return has the larger kind.
11016 @item @emph{Example}:
11017 @smallexample
11018 PROGRAM test_xor
11019   LOGICAL :: T = .TRUE., F = .FALSE.
11020   INTEGER :: a, b
11021   DATA a / Z'F' /, b / Z'3' /
11023   WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11024   WRITE (*,*) XOR(a, b)
11025 END PROGRAM
11026 @end smallexample
11028 @item @emph{See also}:
11029 Fortran 95 elemental function: @ref{IEOR}
11030 @end table
11034 @node Intrinsic Modules
11035 @chapter Intrinsic Modules
11036 @cindex intrinsic Modules
11038 @c @node ISO_FORTRAN_ENV
11039 @section @code{ISO_FORTRAN_ENV}
11040 @table @asis
11041 @item @emph{Standard}:
11042 Fortran 2003 and later
11043 @end table
11045 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11046 named constants:
11048 @table @asis
11049 @item @code{CHARACTER_STORAGE_SIZE}:
11050 Size in bits of the character storage unit.
11052 @item @code{ERROR_UNIT}:
11053 Identifies the preconnected unit used for error reporting.
11055 @item @code{FILE_STORAGE_SIZE}:
11056 Size in bits of the file-storage unit.
11058 @item @code{INPUT_UNIT}:
11059 Identifies the preconnected unit identified by the asterisk
11060 (@code{*}) in @code{READ} statement.
11062 @item @code{IOSTAT_END}:
11063 The value assigned to the variable passed to the IOSTAT= specifier of
11064 an input/output statement if an end-of-file condition occurred.
11066 @item @code{IOSTAT_EOR}:
11067 The value assigned to the variable passed to the IOSTAT= specifier of
11068 an input/output statement if an end-of-record condition occurred.
11070 @item @code{NUMERIC_STORAGE_SIZE}:
11071 The size in bits of the numeric storage unit.
11073 @item @code{OUTPUT_UNIT}:
11074 Identifies the preconnected unit identified by the asterisk
11075 (@code{*}) in @code{WRITE} statement.
11076 @end table
11078 @c @node ISO_C_BINDING
11079 @section @code{ISO_C_BINDING}
11080 @table @asis
11081 @item @emph{Standard}:
11082 Fortran 2003 and later, GNU extensions
11083 @end table
11085 The following intrinsic procedures are provided by the module; their
11086 definition can be found in the section Intrinsic Procedures of this
11087 manual.
11089 @table @asis
11090 @item @code{C_ASSOCIATED}
11091 @item @code{C_F_POINTER}
11092 @item @code{C_F_PROCPOINTER}
11093 @item @code{C_FUNLOC}
11094 @item @code{C_LOC}
11095 @end table
11097 The @code{ISO_C_BINDING} module provides the following named constants of the
11098 type integer, which can be used as KIND type parameter. Note that GNU
11099 Fortran currently does not support the @code{C_INT_FAST...} KIND type
11100 parameters (marked by an asterisk (@code{*}) in the list below).
11101 The @code{C_INT_FAST...} parameters have therefore the value @math{-2}
11102 and cannot be used as KIND type parameter of the @code{INTEGER} type.
11104 In addition to the integer named constants required by the Fortran 2003 
11105 standard, GNU Fortran provides as an extension named constants for the 
11106 128-bit integer types supported by the C compiler: @code{C_INT128_T, 
11107 C_INT_LEAST128_T, C_INT_FAST128_T}.
11109 @multitable @columnfractions .15 .35 .35 .35
11110 @item Fortran Type  @tab Named constant         @tab C type                                @tab Extension
11111 @item @code{INTEGER}@tab @code{C_INT}           @tab @code{int}
11112 @item @code{INTEGER}@tab @code{C_SHORT}         @tab @code{short int}
11113 @item @code{INTEGER}@tab @code{C_LONG}          @tab @code{long int}
11114 @item @code{INTEGER}@tab @code{C_LONG_LONG}     @tab @code{long long int}
11115 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR}   @tab @code{signed char}/@code{unsigned char}
11116 @item @code{INTEGER}@tab @code{C_SIZE_T}        @tab @code{size_t}
11117 @item @code{INTEGER}@tab @code{C_INT8_T}        @tab @code{int8_t}
11118 @item @code{INTEGER}@tab @code{C_INT16_T}       @tab @code{int16_t}
11119 @item @code{INTEGER}@tab @code{C_INT32_T}       @tab @code{int32_t}
11120 @item @code{INTEGER}@tab @code{C_INT64_T}       @tab @code{int64_t}
11121 @item @code{INTEGER}@tab @code{C_INT128_T}       @tab @code{int128_t}                      @tab Ext.
11122 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T}  @tab @code{int_least8_t}
11123 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11124 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11125 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11126 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T} @tab @code{int_least128_t}                @tab Ext.
11127 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}*  @tab @code{int_fast8_t}
11128 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}* @tab @code{int_fast16_t}
11129 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}* @tab @code{int_fast32_t}
11130 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}* @tab @code{int_fast64_t}
11131 @item @code{INTEGER}@tab @code{C_INT_FAST128_T}* @tab @code{int_fast128_t}                 @tab Ext.
11132 @item @code{INTEGER}@tab @code{C_INTMAX_T}      @tab @code{intmax_t}
11133 @item @code{INTEGER}@tab @code{C_INTPTR_T}      @tab @code{intptr_t}
11134 @item @code{REAL}   @tab @code{C_FLOAT}         @tab @code{float}
11135 @item @code{REAL}   @tab @code{C_DOUBLE}        @tab @code{double}
11136 @item @code{REAL}   @tab @code{C_LONG_DOUBLE}   @tab @code{long double}
11137 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11138 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11139 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11140 @item @code{LOGICAL}@tab @code{C_BOOL}          @tab @code{_Bool}
11141 @item @code{CHARACTER}@tab @code{C_CHAR}        @tab @code{char}
11142 @end multitable
11144 Additionally, the following @code{(CHARACTER(KIND=C_CHAR)} are
11145 defined.
11147 @multitable @columnfractions .20 .45 .15
11148 @item Name                     @tab C definition    @tab Value
11149 @item @code{C_NULL_CHAR}       @tab null character  @tab @code{'\0'}
11150 @item @code{C_ALERT}           @tab alert           @tab @code{'\a'}
11151 @item @code{C_BACKSPACE}       @tab backspace       @tab @code{'\b'}
11152 @item @code{C_FORM_FEED}       @tab form feed       @tab @code{'\f'}
11153 @item @code{C_NEW_LINE}        @tab new line        @tab @code{'\n'}
11154 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11155 @item @code{C_HORIZONTAL_TAB}  @tab horizontal tab  @tab @code{'\t'}
11156 @item @code{C_VERTICAL_TAB}    @tab vertical tab    @tab @code{'\v'}
11157 @end multitable
11159 @c @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11160 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11161 @table @asis
11162 @item @emph{Standard}:
11163 OpenMP Application Program Interface v2.5
11164 @end table
11167 The OpenMP Fortran runtime library routines are provided both in
11168 a form of two Fortran 90 modules, named @code{OMP_LIB} and 
11169 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11170 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11171 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11172 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11173 below.
11175 For details refer to the actual
11176 @uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
11177 OpenMP Application Program Interface v2.5}.
11179 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11180 named constants:
11182 @table @asis
11183 @item @code{omp_integer_kind}
11184 @item @code{omp_logical_kind}
11185 @item @code{omp_lock_kind}
11186 @item @code{omp_nest_lock_kind}
11187 @end table