OSDN Git Service

0a8bba01cd9f8dee0be6c8ed2df3546dd950beac
[pf3gnuchains/gcc-fork.git] / gcc / fortran / intrinsic.texi
1 @ignore
2 Copyright (C) 2005, 2006, 2007, 2008, 2009
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.   
5 For copying conditions, see the file gfortran.texi.
6
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 ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below).  A copy of the license is included in the gfdl(7) man page.
13
14
15 Some basic guidelines for editing this document:
16
17   (1) The intrinsic procedures are to be listed in alphabetical order.
18   (2) The generic name is to be used.
19   (3) The specific names are included in the function index and in a
20       table at the end of the node (See ABS entry).
21   (4) Try to maintain the same style for each entry.
22
23
24 @end ignore
25
26 @tex
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
33 @end tex
34
35
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
39
40 @menu
41 * Introduction:         Introduction to Intrinsics
42 * @code{ABORT}:         ABORT,     Abort the program     
43 * @code{ABS}:           ABS,       Absolute value     
44 * @code{ACCESS}:        ACCESS,    Checks file access modes
45 * @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}:          ACOS,      Arccosine function
47 * @code{ACOSH}:         ACOSH,     Hyperbolic arccosine function
48 * @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
49 * @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
50 * @code{AIMAG}:         AIMAG,     Imaginary part of complex number
51 * @code{AINT}:          AINT,      Truncate to a whole number
52 * @code{ALARM}:         ALARM,     Set an alarm clock
53 * @code{ALL}:           ALL,       Determine if all values are true
54 * @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
55 * @code{AND}:           AND,       Bitwise logical AND
56 * @code{ANINT}:         ANINT,     Nearest whole number
57 * @code{ANY}:           ANY,       Determine if any values are true
58 * @code{ASIN}:          ASIN,      Arcsine function
59 * @code{ASINH}:         ASINH,     Hyperbolic arcsine function
60 * @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}:          ATAN,      Arctangent function
62 * @code{ATAN2}:         ATAN2,     Arctangent function
63 * @code{ATANH}:         ATANH,     Hyperbolic arctangent function
64 * @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
65 * @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
66 * @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
67 * @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
68 * @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
69 * @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
70 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
71 * @code{BTEST}:         BTEST,     Bit test function
72 * @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
73 * @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
74 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
75 * @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
76 * @code{C_LOC}:         C_LOC,     Obtain the C address of an object
77 * @code{C_SIZEOF}:      C_SIZEOF,  Size in bytes of an expression
78 * @code{CEILING}:       CEILING,   Integer ceiling function
79 * @code{CHAR}:          CHAR,      Integer-to-character conversion function
80 * @code{CHDIR}:         CHDIR,     Change working directory
81 * @code{CHMOD}:         CHMOD,     Change access permissions of files
82 * @code{CMPLX}:         CMPLX,     Complex conversion function
83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
84 * @code{COMPLEX}:       COMPLEX,   Complex conversion function
85 * @code{CONJG}:         CONJG,     Complex conjugate function
86 * @code{COS}:           COS,       Cosine function
87 * @code{COSH}:          COSH,      Hyperbolic cosine function
88 * @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
89 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
90 * @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
91 * @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
93 * @code{DBLE}:          DBLE,      Double precision conversion function
94 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
95 * @code{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{LEADZ}:         LEADZ,     Number of leading zero bits of an integer
168 * @code{LEN}:           LEN,       Length of a character entity
169 * @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
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{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
180 * @code{LOGICAL}:       LOGICAL,   Convert to logical type
181 * @code{LONG}:          LONG,      Convert to integer type
182 * @code{LSHIFT}:        LSHIFT,    Left shift bits
183 * @code{LSTAT}:         LSTAT,     Get file status
184 * @code{LTIME}:         LTIME,     Convert time to local time info
185 * @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
186 * @code{MATMUL}:        MATMUL,    matrix multiplication
187 * @code{MAX}:           MAX,       Maximum value of an argument list
188 * @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
189 * @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
190 * @code{MAXVAL}:        MAXVAL,    Maximum value of an array
191 * @code{MCLOCK}:        MCLOCK,    Time function
192 * @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
193 * @code{MERGE}:         MERGE,     Merge arrays
194 * @code{MIN}:           MIN,       Minimum value of an argument list
195 * @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
196 * @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
197 * @code{MINVAL}:        MINVAL,    Minimum value of an array
198 * @code{MOD}:           MOD,       Remainder function
199 * @code{MODULO}:        MODULO,    Modulo function
200 * @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
201 * @code{MVBITS}:        MVBITS,    Move bits from one integer to another
202 * @code{NEAREST}:       NEAREST,   Nearest representable number
203 * @code{NEW_LINE}:      NEW_LINE,  New line character
204 * @code{NINT}:          NINT,      Nearest whole number
205 * @code{NOT}:           NOT,       Logical negation
206 * @code{NULL}:          NULL,      Function that returns an disassociated pointer
207 * @code{OR}:            OR,        Bitwise logical OR
208 * @code{PACK}:          PACK,      Pack an array into an array of rank one
209 * @code{PERROR}:        PERROR,    Print system error message
210 * @code{PRECISION}:     PRECISION, Decimal precision of a real kind
211 * @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
212 * @code{PRODUCT}:       PRODUCT,   Product of array elements
213 * @code{RADIX}:         RADIX,     Base of a data model
214 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
215 * @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
216 * @code{RAND}:          RAND,      Real pseudo-random number
217 * @code{RANGE}:         RANGE,     Decimal exponent range
218 * @code{RAN}:           RAN,       Real pseudo-random number
219 * @code{REAL}:          REAL,      Convert to real type 
220 * @code{RENAME}:        RENAME,    Rename a file
221 * @code{REPEAT}:        REPEAT,    Repeated string concatenation
222 * @code{RESHAPE}:       RESHAPE,   Function to reshape an array
223 * @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
224 * @code{RSHIFT}:        RSHIFT,    Right shift bits
225 * @code{SCALE}:         SCALE,     Scale a real value
226 * @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
227 * @code{SECNDS}:        SECNDS,    Time function
228 * @code{SECOND}:        SECOND,    CPU time function
229 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
230 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
231 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
232 * @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
233 * @code{SHAPE}:         SHAPE,     Determine the shape of an array
234 * @code{SIGN}:          SIGN,      Sign copying function
235 * @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
236 * @code{SIN}:           SIN,       Sine function
237 * @code{SINH}:          SINH,      Hyperbolic sine function
238 * @code{SIZE}:          SIZE,      Function to determine the size of an array
239 * @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
240 * @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
241 * @code{SNGL}:          SNGL,      Convert double precision real to default real
242 * @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
243 * @code{SPREAD}:        SPREAD,    Add a dimension to an array 
244 * @code{SQRT}:          SQRT,      Square-root function
245 * @code{SRAND}:         SRAND,     Reinitialize the random number generator
246 * @code{STAT}:          STAT,      Get file status
247 * @code{SUM}:           SUM,       Sum of array elements
248 * @code{SYMLNK}:        SYMLNK,    Create a symbolic link
249 * @code{SYSTEM}:        SYSTEM,    Execute a shell command
250 * @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
251 * @code{TAN}:           TAN,       Tangent function
252 * @code{TANH}:          TANH,      Hyperbolic tangent function
253 * @code{TIME}:          TIME,      Time function
254 * @code{TIME8}:         TIME8,     Time function (64-bit)
255 * @code{TINY}:          TINY,      Smallest positive number of a real kind
256 * @code{TRAILZ}:        TRAILZ,    Number of trailing zero bits of an integer
257 * @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
258 * @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
259 * @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
260 * @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
261 * @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
262 * @code{UMASK}:         UMASK,     Set the file creation mask
263 * @code{UNLINK}:        UNLINK,    Remove a file from the file system
264 * @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
265 * @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
266 * @code{XOR}:           XOR,       Bitwise logical exclusive or
267 @end menu
268
269 @node Introduction to Intrinsics
270 @section Introduction to intrinsic procedures
271
272 The intrinsic procedures provided by GNU Fortran include all of the
273 intrinsic procedures required by the Fortran 95 standard, a set of
274 intrinsic procedures for backwards compatibility with G77, and a
275 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
276 standards.  Any conflict between a description here and a description in
277 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
278 2008 standard is unintentional, and the standard(s) should be considered
279 authoritative.
280
281 The enumeration of the @code{KIND} type parameter is processor defined in
282 the Fortran 95 standard.  GNU Fortran defines the default integer type and
283 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
284 respectively.  The standard mandates that both data types shall have
285 another kind, which have more precision.  On typical target architectures
286 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
287 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
288 In the description of generic intrinsic procedures, the kind type parameter
289 will be specified by @code{KIND=*}, and in the description of specific
290 names for an intrinsic procedure the kind type parameter will be explicitly
291 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
292 brevity the optional @code{KIND=} syntax will be omitted.
293
294 Many of the intrinsic procedures take one or more optional arguments.
295 This document follows the convention used in the Fortran 95 standard,
296 and denotes such arguments by square brackets.
297
298 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
299 which can be used to restrict the set of intrinsic procedures to a 
300 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
301 option, and so all intrinsic procedures described here are accepted.  There
302 is one caveat.  For a select group of intrinsic procedures, @command{g77}
303 implemented both a function and a subroutine.  Both classes 
304 have been implemented in @command{gfortran} for backwards compatibility
305 with @command{g77}.  It is noted here that these functions and subroutines
306 cannot be intermixed in a given subprogram.  In the descriptions that follow,
307 the applicable standard for each intrinsic procedure is noted.
308
309
310
311 @node ABORT
312 @section @code{ABORT} --- Abort the program
313 @fnindex ABORT
314 @cindex program termination, with core dump
315 @cindex terminate program, with core dump
316 @cindex core, dump
317
318 @table @asis
319 @item @emph{Description}:
320 @code{ABORT} causes immediate termination of the program.  On operating
321 systems that support a core dump, @code{ABORT} will produce a core dump even if
322 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
323 purposes.
324 @c TODO: Check if this (with -fno-dump-core) is correct.
325
326 @item @emph{Standard}:
327 GNU extension
328
329 @item @emph{Class}:
330 Subroutine
331
332 @item @emph{Syntax}:
333 @code{CALL ABORT}
334
335 @item @emph{Return value}:
336 Does not return.
337
338 @item @emph{Example}:
339 @smallexample
340 program test_abort
341   integer :: i = 1, j = 2
342   if (i /= j) call abort
343 end program test_abort
344 @end smallexample
345
346 @item @emph{See also}:
347 @ref{EXIT}, @ref{KILL}
348
349 @end table
350
351
352
353 @node ABS
354 @section @code{ABS} --- Absolute value
355 @fnindex ABS
356 @fnindex CABS
357 @fnindex DABS
358 @fnindex IABS
359 @fnindex ZABS
360 @fnindex CDABS
361 @cindex absolute value
362
363 @table @asis
364 @item @emph{Description}:
365 @code{ABS(A)} computes the absolute value of @code{A}.
366
367 @item @emph{Standard}:
368 Fortran 77 and later, has overloads that are GNU extensions
369
370 @item @emph{Class}:
371 Elemental function
372
373 @item @emph{Syntax}:
374 @code{RESULT = ABS(A)}
375
376 @item @emph{Arguments}:
377 @multitable @columnfractions .15 .70
378 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
379 @code{REAL}, or @code{COMPLEX}.
380 @end multitable
381
382 @item @emph{Return value}:
383 The return value is of the same type and
384 kind as the argument except the return value is @code{REAL} for a
385 @code{COMPLEX} argument.
386
387 @item @emph{Example}:
388 @smallexample
389 program test_abs
390   integer :: i = -1
391   real :: x = -1.e0
392   complex :: z = (-1.e0,0.e0)
393   i = abs(i)
394   x = abs(x)
395   x = abs(z)
396 end program test_abs
397 @end smallexample
398
399 @item @emph{Specific names}:
400 @multitable @columnfractions .20 .20 .20 .25
401 @item Name            @tab Argument            @tab Return type       @tab Standard
402 @item @code{CABS(A)}  @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)}    @tab Fortran 77 and later
403 @item @code{DABS(A)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}    @tab Fortran 77 and later
404 @item @code{IABS(A)}  @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
405 @item @code{ZABS(A)}  @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
406 @item @code{CDABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
407 @end multitable
408 @end table
409
410
411
412 @node ACCESS
413 @section @code{ACCESS} --- Checks file access modes
414 @fnindex ACCESS
415 @cindex file system, access mode
416
417 @table @asis
418 @item @emph{Description}:
419 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 
420 exists, is readable, writable or executable. Except for the
421 executable check, @code{ACCESS} can be replaced by
422 Fortran 95's @code{INQUIRE}.
423
424 @item @emph{Standard}:
425 GNU extension
426
427 @item @emph{Class}:
428 Inquiry function
429
430 @item @emph{Syntax}:
431 @code{RESULT = ACCESS(NAME, MODE)}
432
433 @item @emph{Arguments}:
434 @multitable @columnfractions .15 .70
435 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
436 file name. Tailing blank are ignored unless the character @code{achar(0)}
437 is present, then all characters up to and excluding @code{achar(0)} are
438 used as file name.
439 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
440 file access mode, may be any concatenation of @code{"r"} (readable),
441 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
442 for existence.
443 @end multitable
444
445 @item @emph{Return value}:
446 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
447 accessible in the given mode; otherwise or if an invalid argument
448 has been given for @code{MODE} the value @code{1} is returned.
449
450 @item @emph{Example}:
451 @smallexample
452 program access_test
453   implicit none
454   character(len=*), parameter :: file  = 'test.dat'
455   character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
456   if(access(file,' ') == 0) print *, trim(file),' is exists'
457   if(access(file,'r') == 0) print *, trim(file),' is readable'
458   if(access(file,'w') == 0) print *, trim(file),' is writable'
459   if(access(file,'x') == 0) print *, trim(file),' is executable'
460   if(access(file2,'rwx') == 0) &
461     print *, trim(file2),' is readable, writable and executable'
462 end program access_test
463 @end smallexample
464 @item @emph{Specific names}:
465 @item @emph{See also}:
466
467 @end table
468
469
470
471 @node ACHAR
472 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 
473 @fnindex ACHAR
474 @cindex @acronym{ASCII} collating sequence
475 @cindex collating sequence, @acronym{ASCII}
476
477 @table @asis
478 @item @emph{Description}:
479 @code{ACHAR(I)} returns the character located at position @code{I}
480 in the @acronym{ASCII} collating sequence.
481
482 @item @emph{Standard}:
483 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
484
485 @item @emph{Class}:
486 Elemental function
487
488 @item @emph{Syntax}:
489 @code{RESULT = ACHAR(I [, KIND])}
490
491 @item @emph{Arguments}:
492 @multitable @columnfractions .15 .70
493 @item @var{I}    @tab The type shall be @code{INTEGER}.
494 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
495 expression indicating the kind parameter of the result.
496 @end multitable
497
498 @item @emph{Return value}:
499 The return value is of type @code{CHARACTER} with a length of one.
500 If the @var{KIND} argument is present, the return value is of the
501 specified kind and of the default kind otherwise.
502
503 @item @emph{Example}:
504 @smallexample
505 program test_achar
506   character c
507   c = achar(32)
508 end program test_achar
509 @end smallexample
510
511 @item @emph{Note}:
512 See @ref{ICHAR} for a discussion of converting between numerical values
513 and formatted string representations.
514
515 @item @emph{See also}:
516 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
517
518 @end table
519
520
521
522 @node ACOS
523 @section @code{ACOS} --- Arccosine function 
524 @fnindex ACOS
525 @fnindex DACOS
526 @cindex trigonometric function, cosine, inverse
527 @cindex cosine, inverse
528
529 @table @asis
530 @item @emph{Description}:
531 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
532
533 @item @emph{Standard}:
534 Fortran 77 and later
535
536 @item @emph{Class}:
537 Elemental function
538
539 @item @emph{Syntax}:
540 @code{RESULT = ACOS(X)}
541
542 @item @emph{Arguments}:
543 @multitable @columnfractions .15 .70
544 @item @var{X} @tab The type shall be @code{REAL} with a magnitude that is
545 less than or equal to one.
546 @end multitable
547
548 @item @emph{Return value}:
549 The return value is of type @code{REAL} and it lies in the
550 range @math{ 0 \leq \acos(x) \leq \pi}. The return value if of the same
551 kind as @var{X}.
552
553 @item @emph{Example}:
554 @smallexample
555 program test_acos
556   real(8) :: x = 0.866_8
557   x = acos(x)
558 end program test_acos
559 @end smallexample
560
561 @item @emph{Specific names}:
562 @multitable @columnfractions .20 .20 .20 .25
563 @item Name            @tab Argument          @tab Return type       @tab Standard
564 @item @code{DACOS(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
565 @end multitable
566
567 @item @emph{See also}:
568 Inverse function: @ref{COS}
569
570 @end table
571
572
573
574 @node ACOSH
575 @section @code{ACOSH} --- Hyperbolic arccosine function
576 @fnindex ACOSH
577 @fnindex DACOSH
578 @cindex area hyperbolic cosine
579 @cindex hyperbolic arccosine
580 @cindex hyperbolic function, cosine, inverse
581 @cindex cosine, hyperbolic, inverse
582
583 @table @asis
584 @item @emph{Description}:
585 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
586 @code{COSH(X)}).
587
588 @item @emph{Standard}:
589 Fortran 2008 and later
590
591 @item @emph{Class}:
592 Elemental function
593
594 @item @emph{Syntax}:
595 @code{RESULT = ACOSH(X)}
596
597 @item @emph{Arguments}:
598 @multitable @columnfractions .15 .70
599 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
600 @end multitable
601
602 @item @emph{Return value}:
603 The return value has the same type and kind as @var{X}
604
605 @item @emph{Example}:
606 @smallexample
607 PROGRAM test_acosh
608   REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
609   WRITE (*,*) ACOSH(x)
610 END PROGRAM
611 @end smallexample
612
613 @item @emph{Specific names}:
614 @multitable @columnfractions .20 .20 .20 .25
615 @item Name             @tab Argument          @tab Return type       @tab Standard
616 @item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
617 @end multitable
618
619 @item @emph{See also}:
620 Inverse function: @ref{COSH}
621 @end table
622
623
624
625 @node ADJUSTL
626 @section @code{ADJUSTL} --- Left adjust a string 
627 @fnindex ADJUSTL
628 @cindex string, adjust left
629 @cindex adjust string
630
631 @table @asis
632 @item @emph{Description}:
633 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
634 Spaces are inserted at the end of the string as needed.
635
636 @item @emph{Standard}:
637 Fortran 90 and later
638
639 @item @emph{Class}:
640 Elemental function
641
642 @item @emph{Syntax}:
643 @code{RESULT = ADJUSTL(STRING)}
644
645 @item @emph{Arguments}:
646 @multitable @columnfractions .15 .70
647 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
648 @end multitable
649
650 @item @emph{Return value}:
651 The return value is of type @code{CHARACTER} and of the same kind as
652 @var{STRING} where leading spaces are removed and the same number of
653 spaces are inserted on the end of @var{STRING}.
654
655 @item @emph{Example}:
656 @smallexample
657 program test_adjustl
658   character(len=20) :: str = '   gfortran'
659   str = adjustl(str)
660   print *, str
661 end program test_adjustl
662 @end smallexample
663
664 @item @emph{See also}:
665 @ref{ADJUSTR}, @ref{TRIM}
666 @end table
667
668
669
670 @node ADJUSTR
671 @section @code{ADJUSTR} --- Right adjust a string 
672 @fnindex ADJUSTR
673 @cindex string, adjust right
674 @cindex adjust string
675
676 @table @asis
677 @item @emph{Description}:
678 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
679 Spaces are inserted at the start of the string as needed.
680
681 @item @emph{Standard}:
682 Fortran 95 and later
683
684 @item @emph{Class}:
685 Elemental function
686
687 @item @emph{Syntax}:
688 @code{RESULT = ADJUSTR(STRING)}
689
690 @item @emph{Arguments}:
691 @multitable @columnfractions .15 .70
692 @item @var{STR} @tab The type shall be @code{CHARACTER}.
693 @end multitable
694
695 @item @emph{Return value}:
696 The return value is of type @code{CHARACTER} and of the same kind as
697 @var{STRING} where trailing spaces are removed and the same number of
698 spaces are inserted at the start of @var{STRING}.
699
700 @item @emph{Example}:
701 @smallexample
702 program test_adjustr
703   character(len=20) :: str = 'gfortran'
704   str = adjustr(str)
705   print *, str
706 end program test_adjustr
707 @end smallexample
708
709 @item @emph{See also}:
710 @ref{ADJUSTL}, @ref{TRIM}
711 @end table
712
713
714
715 @node AIMAG
716 @section @code{AIMAG} --- Imaginary part of complex number  
717 @fnindex AIMAG
718 @fnindex DIMAG
719 @fnindex IMAG
720 @fnindex IMAGPART
721 @cindex complex numbers, imaginary part
722
723 @table @asis
724 @item @emph{Description}:
725 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
726 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
727 for compatibility with @command{g77}, and their use in new code is 
728 strongly discouraged.
729
730 @item @emph{Standard}:
731 Fortran 77 and later, has overloads that are GNU extensions
732
733 @item @emph{Class}:
734 Elemental function
735
736 @item @emph{Syntax}:
737 @code{RESULT = AIMAG(Z)}
738
739 @item @emph{Arguments}:
740 @multitable @columnfractions .15 .70
741 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
742 @end multitable
743
744 @item @emph{Return value}:
745 The return value is of type @code{REAL} with the
746 kind type parameter of the argument.
747
748 @item @emph{Example}:
749 @smallexample
750 program test_aimag
751   complex(4) z4
752   complex(8) z8
753   z4 = cmplx(1.e0_4, 0.e0_4)
754   z8 = cmplx(0.e0_8, 1.e0_8)
755   print *, aimag(z4), dimag(z8)
756 end program test_aimag
757 @end smallexample
758
759 @item @emph{Specific names}:
760 @multitable @columnfractions .20 .20 .20 .25
761 @item Name            @tab Argument            @tab Return type       @tab Standard
762 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}    @tab GNU extension
763 @item @code{IMAG(Z)}  @tab @code{COMPLEX Z} @tab @code{REAL}    @tab GNU extension
764 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
765 @end multitable
766 @end table
767
768
769
770 @node AINT
771 @section @code{AINT} --- Truncate to a whole number
772 @fnindex AINT
773 @fnindex DINT
774 @cindex floor
775 @cindex rounding, floor
776
777 @table @asis
778 @item @emph{Description}:
779 @code{AINT(A [, KIND])} truncates its argument to a whole number.
780
781 @item @emph{Standard}:
782 Fortran 77 and later
783
784 @item @emph{Class}:
785 Elemental function
786
787 @item @emph{Syntax}:
788 @code{RESULT = AINT(A [, KIND])} 
789
790 @item @emph{Arguments}:
791 @multitable @columnfractions .15 .70
792 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
793 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
794 expression indicating the kind parameter of the result.
795 @end multitable
796
797 @item @emph{Return value}:
798 The return value is of type @code{REAL} with the kind type parameter of the
799 argument if the optional @var{KIND} is absent; otherwise, the kind
800 type parameter will be given by @var{KIND}.  If the magnitude of 
801 @var{X} is less than one, @code{AINT(X)} returns zero.  If the
802 magnitude is equal to or greater than one then it returns the largest
803 whole number that does not exceed its magnitude.  The sign is the same
804 as the sign of @var{X}. 
805
806 @item @emph{Example}:
807 @smallexample
808 program test_aint
809   real(4) x4
810   real(8) x8
811   x4 = 1.234E0_4
812   x8 = 4.321_8
813   print *, aint(x4), dint(x8)
814   x8 = aint(x4,8)
815 end program test_aint
816 @end smallexample
817
818 @item @emph{Specific names}:
819 @multitable @columnfractions .20 .20 .20 .25
820 @item Name           @tab Argument         @tab Return type      @tab Standard
821 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab Fortran 77 and later
822 @end multitable
823 @end table
824
825
826
827 @node ALARM
828 @section @code{ALARM} --- Execute a routine after a given delay
829 @fnindex ALARM
830 @cindex delayed execution
831
832 @table @asis
833 @item @emph{Description}:
834 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
835 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
836 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
837 supplied, it will be returned with the number of seconds remaining until
838 any previously scheduled alarm was due to be delivered, or zero if there
839 was no previously scheduled alarm.
840
841 @item @emph{Standard}:
842 GNU extension
843
844 @item @emph{Class}:
845 Subroutine
846
847 @item @emph{Syntax}:
848 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
849
850 @item @emph{Arguments}:
851 @multitable @columnfractions .15 .70
852 @item @var{SECONDS} @tab The type of the argument shall be a scalar
853 @code{INTEGER}. It is @code{INTENT(IN)}.
854 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
855 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 
856 values may be either @code{SIG_IGN=1} to ignore the alarm generated 
857 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
858 @item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
859 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
860 @end multitable
861
862 @item @emph{Example}:
863 @smallexample
864 program test_alarm
865   external handler_print
866   integer i
867   call alarm (3, handler_print, i)
868   print *, i
869   call sleep(10)
870 end program test_alarm
871 @end smallexample
872 This will cause the external routine @var{handler_print} to be called
873 after 3 seconds.
874 @end table
875
876
877
878 @node ALL
879 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 
880 @fnindex ALL
881 @cindex array, apply condition
882 @cindex array, condition testing
883
884 @table @asis
885 @item @emph{Description}:
886 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
887 in the array along dimension @var{DIM}.
888
889 @item @emph{Standard}:
890 Fortran 95 and later
891
892 @item @emph{Class}:
893 Transformational function
894
895 @item @emph{Syntax}:
896 @code{RESULT = ALL(MASK [, DIM])}
897
898 @item @emph{Arguments}:
899 @multitable @columnfractions .15 .70
900 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
901 it shall not be scalar.
902 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
903 with a value that lies between one and the rank of @var{MASK}.
904 @end multitable
905
906 @item @emph{Return value}:
907 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
908 the kind type parameter is the same as the kind type parameter of
909 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
910 an array with the rank of @var{MASK} minus 1.  The shape is determined from
911 the shape of @var{MASK} where the @var{DIM} dimension is elided. 
912
913 @table @asis
914 @item (A)
915 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
916 It also is true if @var{MASK} has zero size; otherwise, it is false.
917 @item (B)
918 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
919 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
920 is determined by applying @code{ALL} to the array sections.
921 @end table
922
923 @item @emph{Example}:
924 @smallexample
925 program test_all
926   logical l
927   l = all((/.true., .true., .true./))
928   print *, l
929   call section
930   contains
931     subroutine section
932       integer a(2,3), b(2,3)
933       a = 1
934       b = 1
935       b(2,2) = 2
936       print *, all(a .eq. b, 1)
937       print *, all(a .eq. b, 2)
938     end subroutine section
939 end program test_all
940 @end smallexample
941 @end table
942
943
944
945 @node ALLOCATED
946 @section @code{ALLOCATED} --- Status of an allocatable entity
947 @fnindex ALLOCATED
948 @cindex allocation, status
949
950 @table @asis
951 @item @emph{Description}:
952 @code{ALLOCATED(ARRAY)} checks the status of whether @var{X} is allocated.
953
954 @item @emph{Standard}:
955 Fortran 95 and later
956
957 @item @emph{Class}:
958 Inquiry function
959
960 @item @emph{Syntax}:
961 @code{RESULT = ALLOCATED(ARRAY)}
962
963 @item @emph{Arguments}:
964 @multitable @columnfractions .15 .70
965 @item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
966 @end multitable
967
968 @item @emph{Return value}:
969 The return value is a scalar @code{LOGICAL} with the default logical
970 kind type parameter.  If @var{ARRAY} is allocated, @code{ALLOCATED(ARRAY)}
971 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.} 
972
973 @item @emph{Example}:
974 @smallexample
975 program test_allocated
976   integer :: i = 4
977   real(4), allocatable :: x(:)
978   if (.not. allocated(x)) allocate(x(i))
979 end program test_allocated
980 @end smallexample
981 @end table
982
983
984
985 @node AND
986 @section @code{AND} --- Bitwise logical AND
987 @fnindex AND
988 @cindex bitwise logical and
989 @cindex logical and, bitwise
990
991 @table @asis
992 @item @emph{Description}:
993 Bitwise logical @code{AND}.
994
995 This intrinsic routine is provided for backwards compatibility with 
996 GNU Fortran 77.  For integer arguments, programmers should consider
997 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
998
999 @item @emph{Standard}:
1000 GNU extension
1001
1002 @item @emph{Class}:
1003 Function
1004
1005 @item @emph{Syntax}:
1006 @code{RESULT = AND(I, J)}
1007
1008 @item @emph{Arguments}:
1009 @multitable @columnfractions .15 .70
1010 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1011 type or a scalar @code{LOGICAL} type.
1012 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1013 @end multitable
1014
1015 @item @emph{Return value}:
1016 The return type is either a scalar @code{INTEGER} or a scalar
1017 @code{LOGICAL}.  If the kind type parameters differ, then the
1018 smaller kind type is implicitly converted to larger kind, and the 
1019 return has the larger kind.
1020
1021 @item @emph{Example}:
1022 @smallexample
1023 PROGRAM test_and
1024   LOGICAL :: T = .TRUE., F = .FALSE.
1025   INTEGER :: a, b
1026   DATA a / Z'F' /, b / Z'3' /
1027
1028   WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1029   WRITE (*,*) AND(a, b)
1030 END PROGRAM
1031 @end smallexample
1032
1033 @item @emph{See also}:
1034 Fortran 95 elemental function: @ref{IAND}
1035 @end table
1036
1037
1038
1039 @node ANINT
1040 @section @code{ANINT} --- Nearest whole number
1041 @fnindex ANINT
1042 @fnindex DNINT
1043 @cindex ceiling
1044 @cindex rounding, ceiling
1045
1046 @table @asis
1047 @item @emph{Description}:
1048 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1049
1050 @item @emph{Standard}:
1051 Fortran 77 and later
1052
1053 @item @emph{Class}:
1054 Elemental function
1055
1056 @item @emph{Syntax}:
1057 @code{RESULT = ANINT(A [, KIND])}
1058
1059 @item @emph{Arguments}:
1060 @multitable @columnfractions .15 .70
1061 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
1062 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1063 expression indicating the kind parameter of the result.
1064 @end multitable
1065
1066 @item @emph{Return value}:
1067 The return value is of type real with the kind type parameter of the
1068 argument if the optional @var{KIND} is absent; otherwise, the kind
1069 type parameter will be given by @var{KIND}.  If @var{A} is greater than
1070 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
1071 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1072
1073 @item @emph{Example}:
1074 @smallexample
1075 program test_anint
1076   real(4) x4
1077   real(8) x8
1078   x4 = 1.234E0_4
1079   x8 = 4.321_8
1080   print *, anint(x4), dnint(x8)
1081   x8 = anint(x4,8)
1082 end program test_anint
1083 @end smallexample
1084
1085 @item @emph{Specific names}:
1086 @multitable @columnfractions .20 .20 .20 .25
1087 @item Name            @tab Argument         @tab Return type      @tab Standard
1088 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
1089 @end multitable
1090 @end table
1091
1092
1093
1094 @node ANY
1095 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 
1096 @fnindex ANY
1097 @cindex array, apply condition
1098 @cindex array, condition testing
1099
1100 @table @asis
1101 @item @emph{Description}:
1102 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1103 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1104
1105 @item @emph{Standard}:
1106 Fortran 95 and later
1107
1108 @item @emph{Class}:
1109 Transformational function
1110
1111 @item @emph{Syntax}:
1112 @code{RESULT = ANY(MASK [, DIM])}
1113
1114 @item @emph{Arguments}:
1115 @multitable @columnfractions .15 .70
1116 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1117 it shall not be scalar.
1118 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1119 with a value that lies between one and the rank of @var{MASK}.
1120 @end multitable
1121
1122 @item @emph{Return value}:
1123 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1124 the kind type parameter is the same as the kind type parameter of
1125 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1126 an array with the rank of @var{MASK} minus 1.  The shape is determined from
1127 the shape of @var{MASK} where the @var{DIM} dimension is elided. 
1128
1129 @table @asis
1130 @item (A)
1131 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1132 otherwise, it is false.  It also is false if @var{MASK} has zero size.
1133 @item (B)
1134 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1135 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1136 is determined by applying @code{ANY} to the array sections.
1137 @end table
1138
1139 @item @emph{Example}:
1140 @smallexample
1141 program test_any
1142   logical l
1143   l = any((/.true., .true., .true./))
1144   print *, l
1145   call section
1146   contains
1147     subroutine section
1148       integer a(2,3), b(2,3)
1149       a = 1
1150       b = 1
1151       b(2,2) = 2
1152       print *, any(a .eq. b, 1)
1153       print *, any(a .eq. b, 2)
1154     end subroutine section
1155 end program test_any
1156 @end smallexample
1157 @end table
1158
1159
1160
1161 @node ASIN
1162 @section @code{ASIN} --- Arcsine function 
1163 @fnindex ASIN
1164 @fnindex DASIN
1165 @cindex trigonometric function, sine, inverse
1166 @cindex sine, inverse
1167
1168 @table @asis
1169 @item @emph{Description}:
1170 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1171
1172 @item @emph{Standard}:
1173 Fortran 77 and later
1174
1175 @item @emph{Class}:
1176 Elemental function
1177
1178 @item @emph{Syntax}:
1179 @code{RESULT = ASIN(X)}
1180
1181 @item @emph{Arguments}:
1182 @multitable @columnfractions .15 .70
1183 @item @var{X} @tab The type shall be @code{REAL}, and a magnitude that is
1184 less than or equal to one.
1185 @end multitable
1186
1187 @item @emph{Return value}:
1188 The return value is of type @code{REAL} and it lies in the
1189 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}.  The kind type
1190 parameter is the same as @var{X}.
1191
1192 @item @emph{Example}:
1193 @smallexample
1194 program test_asin
1195   real(8) :: x = 0.866_8
1196   x = asin(x)
1197 end program test_asin
1198 @end smallexample
1199
1200 @item @emph{Specific names}:
1201 @multitable @columnfractions .20 .20 .20 .25
1202 @item Name            @tab Argument          @tab Return type       @tab Standard
1203 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1204 @end multitable
1205
1206 @item @emph{See also}:
1207 Inverse function: @ref{SIN}
1208
1209 @end table
1210
1211
1212
1213 @node ASINH
1214 @section @code{ASINH} --- Hyperbolic arcsine function
1215 @fnindex ASINH
1216 @fnindex DASINH
1217 @cindex area hyperbolic sine
1218 @cindex hyperbolic arcsine
1219 @cindex hyperbolic function, sine, inverse
1220 @cindex sine, hyperbolic, inverse
1221
1222 @table @asis
1223 @item @emph{Description}:
1224 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1225
1226 @item @emph{Standard}:
1227 Fortran 2008 and later
1228
1229 @item @emph{Class}:
1230 Elemental function
1231
1232 @item @emph{Syntax}:
1233 @code{RESULT = ASINH(X)}
1234
1235 @item @emph{Arguments}:
1236 @multitable @columnfractions .15 .70
1237 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1238 @end multitable
1239
1240 @item @emph{Return value}:
1241 The return value is of the same type and kind as  @var{X}.
1242
1243 @item @emph{Example}:
1244 @smallexample
1245 PROGRAM test_asinh
1246   REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1247   WRITE (*,*) ASINH(x)
1248 END PROGRAM
1249 @end smallexample
1250
1251 @item @emph{Specific names}:
1252 @multitable @columnfractions .20 .20 .20 .25
1253 @item Name             @tab Argument          @tab Return type       @tab Standard
1254 @item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1255 @end multitable
1256
1257 @item @emph{See also}:
1258 Inverse function: @ref{SINH}
1259 @end table
1260
1261
1262
1263 @node ASSOCIATED
1264 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 
1265 @fnindex ASSOCIATED
1266 @cindex pointer, status
1267 @cindex association status
1268
1269 @table @asis
1270 @item @emph{Description}:
1271 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1272 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1273
1274 @item @emph{Standard}:
1275 Fortran 95 and later
1276
1277 @item @emph{Class}:
1278 Inquiry function
1279
1280 @item @emph{Syntax}:
1281 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1282
1283 @item @emph{Arguments}:
1284 @multitable @columnfractions .15 .70
1285 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1286 and it can be of any type.
1287 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1288 a target.  It must have the same type, kind type parameter, and
1289 array rank as @var{POINTER}.
1290 @end multitable
1291 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1292 undefined.
1293
1294 @item @emph{Return value}:
1295 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1296 There are several cases:
1297 @table @asis
1298 @item (A) When the optional @var{TARGET} is not present then
1299 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1300 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1301 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units.  If @var{POINTER} is
1302 disassociated, the result is false.
1303 @item (C) If @var{TARGET} is present and an array target, the result is true if
1304 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1305 are arrays whose elements are not zero-sized storage sequences, and
1306 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1307 order.
1308 As in case(B), the result is false, if @var{POINTER} is disassociated.
1309 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1310 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1311 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1312 units.
1313 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1314 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1315 target associated with @var{POINTER} and the target associated with @var{TARGET}
1316 have the same shape, are not zero-sized arrays, are arrays whose elements are
1317 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1318 the same storage units in array element order.
1319 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1320 @end table
1321
1322 @item @emph{Example}:
1323 @smallexample
1324 program test_associated
1325    implicit none
1326    real, target  :: tgt(2) = (/1., 2./)
1327    real, pointer :: ptr(:)
1328    ptr => tgt
1329    if (associated(ptr)     .eqv. .false.) call abort
1330    if (associated(ptr,tgt) .eqv. .false.) call abort
1331 end program test_associated
1332 @end smallexample
1333
1334 @item @emph{See also}:
1335 @ref{NULL}
1336 @end table
1337
1338
1339
1340 @node ATAN
1341 @section @code{ATAN} --- Arctangent function 
1342 @fnindex ATAN
1343 @fnindex DATAN
1344 @cindex trigonometric function, tangent, inverse
1345 @cindex tangent, inverse
1346
1347 @table @asis
1348 @item @emph{Description}:
1349 @code{ATAN(X)} computes the arctangent of @var{X}.
1350
1351 @item @emph{Standard}:
1352 Fortran 77 and later
1353
1354 @item @emph{Class}:
1355 Elemental function
1356
1357 @item @emph{Syntax}:
1358 @code{RESULT = ATAN(X)}
1359
1360 @item @emph{Arguments}:
1361 @multitable @columnfractions .15 .70
1362 @item @var{X} @tab The type shall be @code{REAL}.
1363 @end multitable
1364
1365 @item @emph{Return value}:
1366 The return value is of type @code{REAL} and it lies in the
1367 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1368
1369 @item @emph{Example}:
1370 @smallexample
1371 program test_atan
1372   real(8) :: x = 2.866_8
1373   x = atan(x)
1374 end program test_atan
1375 @end smallexample
1376
1377 @item @emph{Specific names}:
1378 @multitable @columnfractions .20 .20 .20 .25
1379 @item Name            @tab Argument          @tab Return type       @tab Standard
1380 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1381 @end multitable
1382
1383 @item @emph{See also}:
1384 Inverse function: @ref{TAN}
1385
1386 @end table
1387
1388
1389
1390 @node ATAN2
1391 @section @code{ATAN2} --- Arctangent function 
1392 @fnindex ATAN2
1393 @fnindex DATAN2
1394 @cindex trigonometric function, tangent, inverse
1395 @cindex tangent, inverse
1396
1397 @table @asis
1398 @item @emph{Description}:
1399 @code{ATAN2(Y, X)} computes the arctangent of the complex number
1400 @math{X + i Y}.
1401
1402 @item @emph{Standard}:
1403 Fortran 77 and later
1404
1405 @item @emph{Class}:
1406 Elemental function
1407
1408 @item @emph{Syntax}:
1409 @code{RESULT = ATAN2(Y, X)}
1410
1411 @item @emph{Arguments}:
1412 @multitable @columnfractions .15 .70
1413 @item @var{Y} @tab The type shall be @code{REAL}.
1414 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1415 If @var{Y} is zero, then @var{X} must be nonzero.
1416 @end multitable
1417
1418 @item @emph{Return value}:
1419 The return value has the same type and kind type parameter as @var{Y}.
1420 It is the principal value of the complex number @math{X + i Y}.  If
1421 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1422 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1423 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1424 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
1425 is @math{\pi/2}.
1426
1427 @item @emph{Example}:
1428 @smallexample
1429 program test_atan2
1430   real(4) :: x = 1.e0_4, y = 0.5e0_4
1431   x = atan2(y,x)
1432 end program test_atan2
1433 @end smallexample
1434
1435 @item @emph{Specific names}:
1436 @multitable @columnfractions .20 .20 .20 .25
1437 @item Name            @tab Argument          @tab Return type    @tab Standard
1438 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X}, @code{REAL(8) Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1439 @end multitable
1440 @end table
1441
1442
1443
1444 @node ATANH
1445 @section @code{ATANH} --- Hyperbolic arctangent function
1446 @fnindex ASINH
1447 @fnindex DASINH
1448 @cindex area hyperbolic tangent
1449 @cindex hyperbolic arctangent
1450 @cindex hyperbolic function, tangent, inverse
1451 @cindex tangent, hyperbolic, inverse
1452
1453 @table @asis
1454 @item @emph{Description}:
1455 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1456 of @code{TANH(X)}).
1457
1458 @item @emph{Standard}:
1459 Fortran 2008 and later
1460
1461 @item @emph{Class}:
1462 Elemental function
1463
1464 @item @emph{Syntax}:
1465 @code{RESULT = ATANH(X)}
1466
1467 @item @emph{Arguments}:
1468 @multitable @columnfractions .15 .70
1469 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1470 @end multitable
1471
1472 @item @emph{Return value}:
1473 The return value has same type and kind as @var{X}.
1474
1475 @item @emph{Example}:
1476 @smallexample
1477 PROGRAM test_atanh
1478   REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1479   WRITE (*,*) ATANH(x)
1480 END PROGRAM
1481 @end smallexample
1482
1483 @item @emph{Specific names}:
1484 @multitable @columnfractions .20 .20 .20 .25
1485 @item Name             @tab Argument          @tab Return type       @tab Standard
1486 @item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1487 @end multitable
1488
1489 @item @emph{See also}:
1490 Inverse function: @ref{TANH}
1491 @end table
1492
1493
1494
1495 @node BESSEL_J0
1496 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1497 @fnindex BESSEL_J0
1498 @fnindex BESJ0
1499 @fnindex DBESJ0
1500 @cindex Bessel function, first kind
1501
1502 @table @asis
1503 @item @emph{Description}:
1504 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1505 order 0 of @var{X}. This function is available under the name
1506 @code{BESJ0} as a GNU extension.
1507
1508 @item @emph{Standard}:
1509 Fortran 2008 and later
1510
1511 @item @emph{Class}:
1512 Elemental function
1513
1514 @item @emph{Syntax}:
1515 @code{RESULT = BESSEL_J0(X)}
1516
1517 @item @emph{Arguments}:
1518 @multitable @columnfractions .15 .70
1519 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1520 @end multitable
1521
1522 @item @emph{Return value}:
1523 The return value is of type @code{REAL} and lies in the
1524 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1525 kind as @var{X}.
1526
1527 @item @emph{Example}:
1528 @smallexample
1529 program test_besj0
1530   real(8) :: x = 0.0_8
1531   x = bessel_j0(x)
1532 end program test_besj0
1533 @end smallexample
1534
1535 @item @emph{Specific names}:
1536 @multitable @columnfractions .20 .20 .20 .25
1537 @item Name            @tab Argument          @tab Return type       @tab Standard
1538 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1539 @end multitable
1540 @end table
1541
1542
1543
1544 @node BESSEL_J1
1545 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1546 @fnindex BESSEL_J1
1547 @fnindex BESJ1
1548 @fnindex DBESJ1
1549 @cindex Bessel function, first kind
1550
1551 @table @asis
1552 @item @emph{Description}:
1553 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1554 order 1 of @var{X}. This function is available under the name
1555 @code{BESJ1} as a GNU extension.
1556
1557 @item @emph{Standard}:
1558 Fortran 2008
1559
1560 @item @emph{Class}:
1561 Elemental function
1562
1563 @item @emph{Syntax}:
1564 @code{RESULT = BESSEL_J1(X)}
1565
1566 @item @emph{Arguments}:
1567 @multitable @columnfractions .15 .70
1568 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1569 @end multitable
1570
1571 @item @emph{Return value}:
1572 The return value is of type @code{REAL} and it lies in the
1573 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1574 kind as @var{X}.
1575
1576 @item @emph{Example}:
1577 @smallexample
1578 program test_besj1
1579   real(8) :: x = 1.0_8
1580   x = bessel_j1(x)
1581 end program test_besj1
1582 @end smallexample
1583
1584 @item @emph{Specific names}:
1585 @multitable @columnfractions .20 .20 .20 .25
1586 @item Name            @tab Argument          @tab Return type       @tab Standard
1587 @item @code{DBESJ1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1588 @end multitable
1589 @end table
1590
1591
1592
1593 @node BESSEL_JN
1594 @section @code{BESSEL_JN} --- Bessel function of the first kind
1595 @fnindex BESSEL_JN
1596 @fnindex BESJN
1597 @fnindex DBESJN
1598 @cindex Bessel function, first kind
1599
1600 @table @asis
1601 @item @emph{Description}:
1602 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1603 order @var{N} of @var{X}. This function is available under the name
1604 @code{BESJN} as a GNU extension.
1605
1606 If both arguments are arrays, their ranks and shapes shall conform.
1607
1608 @item @emph{Standard}:
1609 Fortran 2008 and later
1610
1611 @item @emph{Class}:
1612 Elemental function
1613
1614 @item @emph{Syntax}:
1615 @code{RESULT = BESSEL_JN(N, X)}
1616
1617 @item @emph{Arguments}:
1618 @multitable @columnfractions .15 .70
1619 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1620 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL}.
1621 @end multitable
1622
1623 @item @emph{Return value}:
1624 The return value is a scalar of type @code{REAL}. It has the same
1625 kind as @var{X}.
1626
1627 @item @emph{Example}:
1628 @smallexample
1629 program test_besjn
1630   real(8) :: x = 1.0_8
1631   x = bessel_jn(5,x)
1632 end program test_besjn
1633 @end smallexample
1634
1635 @item @emph{Specific names}:
1636 @multitable @columnfractions .20 .20 .20 .25
1637 @item Name                @tab Argument            @tab Return type       @tab Standard
1638 @item @code{DBESJN(N, X)} @tab @code{INTEGER N}    @tab @code{REAL(8)}    @tab GNU extension
1639 @item                     @tab @code{REAL(8) X}    @tab                   @tab
1640 @end multitable
1641 @end table
1642
1643
1644
1645 @node BESSEL_Y0
1646 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1647 @fnindex BESSEL_Y0
1648 @fnindex BESY0
1649 @fnindex DBESY0
1650 @cindex Bessel function, second kind
1651
1652 @table @asis
1653 @item @emph{Description}:
1654 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1655 order 0 of @var{X}. This function is available under the name
1656 @code{BESY0} as a GNU extension.
1657
1658 @item @emph{Standard}:
1659 Fortran 2008 and later
1660
1661 @item @emph{Class}:
1662 Elemental function
1663
1664 @item @emph{Syntax}:
1665 @code{RESULT = BESSEL_Y0(X)}
1666
1667 @item @emph{Arguments}:
1668 @multitable @columnfractions .15 .70
1669 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1670 @end multitable
1671
1672 @item @emph{Return value}:
1673 The return value is a scalar of type @code{REAL}. It has the same
1674 kind as @var{X}.
1675
1676 @item @emph{Example}:
1677 @smallexample
1678 program test_besy0
1679   real(8) :: x = 0.0_8
1680   x = bessel_y0(x)
1681 end program test_besy0
1682 @end smallexample
1683
1684 @item @emph{Specific names}:
1685 @multitable @columnfractions .20 .20 .20 .25
1686 @item Name            @tab Argument          @tab Return type       @tab Standard
1687 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1688 @end multitable
1689 @end table
1690
1691
1692
1693 @node BESSEL_Y1
1694 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1695 @fnindex BESSEL_Y1
1696 @fnindex BESY1
1697 @fnindex DBESY1
1698 @cindex Bessel function, second kind
1699
1700 @table @asis
1701 @item @emph{Description}:
1702 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1703 order 1 of @var{X}. This function is available under the name
1704 @code{BESY1} as a GNU extension.
1705
1706 @item @emph{Standard}:
1707 Fortran 2008 and later
1708
1709 @item @emph{Class}:
1710 Elemental function
1711
1712 @item @emph{Syntax}:
1713 @code{RESULT = BESSEL_Y1(X)}
1714
1715 @item @emph{Arguments}:
1716 @multitable @columnfractions .15 .70
1717 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1718 @end multitable
1719
1720 @item @emph{Return value}:
1721 The return value is a scalar of type @code{REAL}. It has the same
1722 kind as @var{X}.
1723
1724 @item @emph{Example}:
1725 @smallexample
1726 program test_besy1
1727   real(8) :: x = 1.0_8
1728   x = bessel_y1(x)
1729 end program test_besy1
1730 @end smallexample
1731
1732 @item @emph{Specific names}:
1733 @multitable @columnfractions .20 .20 .20 .25
1734 @item Name            @tab Argument          @tab Return type       @tab Standard
1735 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1736 @end multitable
1737 @end table
1738
1739
1740
1741 @node BESSEL_YN
1742 @section @code{BESSEL_YN} --- Bessel function of the second kind
1743 @fnindex BESSEL_YN
1744 @fnindex BESYN
1745 @fnindex DBESYN
1746 @cindex Bessel function, second kind
1747
1748 @table @asis
1749 @item @emph{Description}:
1750 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1751 order @var{N} of @var{X}. This function is available under the name
1752 @code{BESYN} as a GNU extension.
1753
1754 If both arguments are arrays, their ranks and shapes shall conform.
1755
1756 @item @emph{Standard}:
1757 Fortran 2008 and later
1758
1759 @item @emph{Class}:
1760 Elemental function
1761
1762 @item @emph{Syntax}:
1763 @code{RESULT = BESSEL_YN(N, X)}
1764
1765 @item @emph{Arguments}:
1766 @multitable @columnfractions .15 .70
1767 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1768 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL}.
1769 @end multitable
1770
1771 @item @emph{Return value}:
1772 The return value is a scalar of type @code{REAL}. It has the same
1773 kind as @var{X}.
1774
1775 @item @emph{Example}:
1776 @smallexample
1777 program test_besyn
1778   real(8) :: x = 1.0_8
1779   x = bessel_yn(5,x)
1780 end program test_besyn
1781 @end smallexample
1782
1783 @item @emph{Specific names}:
1784 @multitable @columnfractions .20 .20 .20 .25
1785 @item Name               @tab Argument            @tab Return type     @tab Standard
1786 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
1787 @item                    @tab @code{REAL(8)    X} @tab                 @tab 
1788 @end multitable
1789 @end table
1790
1791
1792
1793 @node BIT_SIZE
1794 @section @code{BIT_SIZE} --- Bit size inquiry function
1795 @fnindex BIT_SIZE
1796 @cindex bits, number of
1797 @cindex size of a variable, in bits
1798
1799 @table @asis
1800 @item @emph{Description}:
1801 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1802 represented by the type of @var{I}.  The result of @code{BIT_SIZE(I)} is
1803 independent of the actual value of @var{I}.
1804
1805 @item @emph{Standard}:
1806 Fortran 95 and later
1807
1808 @item @emph{Class}:
1809 Inquiry function
1810
1811 @item @emph{Syntax}:
1812 @code{RESULT = BIT_SIZE(I)}
1813
1814 @item @emph{Arguments}:
1815 @multitable @columnfractions .15 .70
1816 @item @var{I} @tab The type shall be @code{INTEGER}.
1817 @end multitable
1818
1819 @item @emph{Return value}:
1820 The return value is of type @code{INTEGER}
1821
1822 @item @emph{Example}:
1823 @smallexample
1824 program test_bit_size
1825     integer :: i = 123
1826     integer :: size
1827     size = bit_size(i)
1828     print *, size
1829 end program test_bit_size
1830 @end smallexample
1831 @end table
1832
1833
1834
1835 @node BTEST
1836 @section @code{BTEST} --- Bit test function
1837 @fnindex BTEST
1838 @cindex bits, testing
1839
1840 @table @asis
1841 @item @emph{Description}:
1842 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1843 in @var{I} is set.  The counting of the bits starts at 0.
1844
1845 @item @emph{Standard}:
1846 Fortran 95 and later
1847
1848 @item @emph{Class}:
1849 Elemental function
1850
1851 @item @emph{Syntax}:
1852 @code{RESULT = BTEST(I, POS)}
1853
1854 @item @emph{Arguments}:
1855 @multitable @columnfractions .15 .70
1856 @item @var{I} @tab The type shall be @code{INTEGER}.
1857 @item @var{POS} @tab The type shall be @code{INTEGER}.
1858 @end multitable
1859
1860 @item @emph{Return value}:
1861 The return value is of type @code{LOGICAL}
1862
1863 @item @emph{Example}:
1864 @smallexample
1865 program test_btest
1866     integer :: i = 32768 + 1024 + 64
1867     integer :: pos
1868     logical :: bool
1869     do pos=0,16
1870         bool = btest(i, pos) 
1871         print *, pos, bool
1872     end do
1873 end program test_btest
1874 @end smallexample
1875 @end table
1876
1877
1878 @node C_ASSOCIATED
1879 @section @code{C_ASSOCIATED} --- Status of a C pointer
1880 @fnindex C_ASSOCIATED
1881 @cindex association status, C pointer
1882 @cindex pointer, C association status
1883
1884 @table @asis
1885 @item @emph{Description}:
1886 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1887 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1888
1889 @item @emph{Standard}:
1890 Fortran 2003 and later
1891
1892 @item @emph{Class}:
1893 Inquiry function
1894
1895 @item @emph{Syntax}:
1896 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1897
1898 @item @emph{Arguments}:
1899 @multitable @columnfractions .15 .70
1900 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1901 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1902 @end multitable
1903
1904 @item @emph{Return value}:
1905 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1906 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1907 point to different addresses.
1908
1909 @item @emph{Example}:
1910 @smallexample
1911 subroutine association_test(a,b)
1912   use iso_c_binding, only: c_associated, c_loc, c_ptr
1913   implicit none
1914   real, pointer :: a
1915   type(c_ptr) :: b
1916   if(c_associated(b, c_loc(a))) &
1917      stop 'b and a do not point to same target'
1918 end subroutine association_test
1919 @end smallexample
1920
1921 @item @emph{See also}:
1922 @ref{C_LOC}, @ref{C_FUNLOC}
1923 @end table
1924
1925
1926 @node C_FUNLOC
1927 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1928 @fnindex C_FUNLOC
1929 @cindex pointer, C address of procedures
1930
1931 @table @asis
1932 @item @emph{Description}:
1933 @code{C_FUNLOC(x)} determines the C address of the argument.
1934
1935 @item @emph{Standard}:
1936 Fortran 2003 and later
1937
1938 @item @emph{Class}:
1939 Inquiry function
1940
1941 @item @emph{Syntax}:
1942 @code{RESULT = C_FUNLOC(x)}
1943
1944 @item @emph{Arguments}:
1945 @multitable @columnfractions .15 .70
1946 @item @var{x} @tab Interoperable function or pointer to such function.
1947 @end multitable
1948
1949 @item @emph{Return value}:
1950 The return value is of type @code{C_FUNPTR} and contains the C address
1951 of the argument.
1952
1953 @item @emph{Example}:
1954 @smallexample
1955 module x
1956   use iso_c_binding
1957   implicit none
1958 contains
1959   subroutine sub(a) bind(c)
1960     real(c_float) :: a
1961     a = sqrt(a)+5.0
1962   end subroutine sub
1963 end module x
1964 program main
1965   use iso_c_binding
1966   use x
1967   implicit none
1968   interface
1969     subroutine my_routine(p) bind(c,name='myC_func')
1970       import :: c_funptr
1971       type(c_funptr), intent(in) :: p
1972     end subroutine
1973   end interface
1974   call my_routine(c_funloc(sub))
1975 end program main
1976 @end smallexample
1977
1978 @item @emph{See also}:
1979 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1980 @end table
1981
1982
1983 @node C_F_PROCPOINTER
1984 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1985 @fnindex C_F_PROCPOINTER
1986 @cindex pointer, C address of pointers
1987
1988 @table @asis
1989 @item @emph{Description}:
1990 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
1991 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
1992
1993 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1994 this function is not fully operable.
1995
1996 @item @emph{Standard}:
1997 Fortran 2003 and later
1998
1999 @item @emph{Class}:
2000 Subroutine
2001
2002 @item @emph{Syntax}:
2003 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2004
2005 @item @emph{Arguments}:
2006 @multitable @columnfractions .15 .70
2007 @item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
2008 @code{INTENT(IN)}.
2009 @item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
2010 @code{INTENT(OUT)}.
2011 @end multitable
2012
2013 @item @emph{Example}:
2014 @smallexample
2015 program main
2016   use iso_c_binding
2017   implicit none
2018   abstract interface
2019     function func(a)
2020       import :: c_float
2021       real(c_float), intent(in) :: a
2022       real(c_float) :: func
2023     end function
2024   end interface
2025   interface
2026      function getIterFunc() bind(c,name="getIterFunc")
2027        import :: c_funptr
2028        type(c_funptr) :: getIterFunc
2029      end function
2030   end interface
2031   type(c_funptr) :: cfunptr
2032   procedure(func), pointer :: myFunc
2033   cfunptr = getIterFunc()
2034   call c_f_procpointer(cfunptr, myFunc)
2035 end program main
2036 @end smallexample
2037
2038 @item @emph{See also}:
2039 @ref{C_LOC}, @ref{C_F_POINTER}
2040 @end table
2041
2042
2043 @node C_F_POINTER
2044 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2045 @fnindex C_F_POINTER
2046 @cindex pointer, convert C to Fortran
2047
2048 @table @asis
2049 @item @emph{Description}:
2050 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2051 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2052 shape.
2053
2054 @item @emph{Standard}:
2055 Fortran 2003 and later
2056
2057 @item @emph{Class}:
2058 Subroutine
2059
2060 @item @emph{Syntax}:
2061 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2062
2063 @item @emph{Arguments}:
2064 @multitable @columnfractions .15 .70
2065 @item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
2066 @code{INTENT(IN)}.
2067 @item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
2068 @code{INTENT(OUT)}.
2069 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2070 with @code{INTENT(IN)}. It shall be present
2071 if and only if @var{fptr} is an array. The size
2072 must be equal to the rank of @var{fptr}.
2073 @end multitable
2074
2075 @item @emph{Example}:
2076 @smallexample
2077 program main
2078   use iso_c_binding
2079   implicit none
2080   interface
2081     subroutine my_routine(p) bind(c,name='myC_func')
2082       import :: c_ptr
2083       type(c_ptr), intent(out) :: p
2084     end subroutine
2085   end interface
2086   type(c_ptr) :: cptr
2087   real,pointer :: a(:)
2088   call my_routine(cptr)
2089   call c_f_pointer(cptr, a, [12])
2090 end program main
2091 @end smallexample
2092
2093 @item @emph{See also}:
2094 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2095 @end table
2096
2097
2098 @node C_LOC
2099 @section @code{C_LOC} --- Obtain the C address of an object
2100 @fnindex C_LOC
2101 @cindex procedure pointer, convert C to Fortran
2102
2103 @table @asis
2104 @item @emph{Description}:
2105 @code{C_LOC(X)} determines the C address of the argument.
2106
2107 @item @emph{Standard}:
2108 Fortran 2003 and later
2109
2110 @item @emph{Class}:
2111 Inquiry function
2112
2113 @item @emph{Syntax}:
2114 @code{RESULT = C_LOC(X)}
2115
2116 @item @emph{Arguments}:
2117 @multitable @columnfractions .15 .70
2118 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2119 or allocated allocatable variable with @code{TARGET} attribute.
2120 @end multitable
2121
2122 @item @emph{Return value}:
2123 The return value is of type @code{C_PTR} and contains the C address
2124 of the argument.
2125
2126 @item @emph{Example}:
2127 @smallexample
2128 subroutine association_test(a,b)
2129   use iso_c_binding, only: c_associated, c_loc, c_ptr
2130   implicit none
2131   real, pointer :: a
2132   type(c_ptr) :: b
2133   if(c_associated(b, c_loc(a))) &
2134      stop 'b and a do not point to same target'
2135 end subroutine association_test
2136 @end smallexample
2137
2138 @item @emph{See also}:
2139 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2140 @end table
2141
2142
2143 @node C_SIZEOF
2144 @section @code{C_SIZEOF} --- Size in bytes of an expression
2145 @fnindex C_SIZEOF
2146 @cindex expression size
2147 @cindex size of an expression
2148
2149 @table @asis
2150 @item @emph{Description}:
2151 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2152 expression @code{X} occupies.
2153
2154 @item @emph{Standard}:
2155 Fortran 2008
2156
2157 @item @emph{Class}:
2158 Intrinsic function
2159
2160 @item @emph{Syntax}:
2161 @code{N = C_SIZEOF(X)}
2162
2163 @item @emph{Arguments}:
2164 @multitable @columnfractions .15 .70
2165 @item @var{X} @tab The argument shall be of any type, rank or shape.
2166 @end multitable
2167
2168 @item @emph{Return value}:
2169 The return value is of type integer and of the system-dependent kind
2170 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2171 number of bytes occupied by the argument.  If the argument has the
2172 @code{POINTER} attribute, the number of bytes of the storage area pointed
2173 to is returned.  If the argument is of a derived type with @code{POINTER}
2174 or @code{ALLOCATABLE} components, the return value doesn't account for
2175 the sizes of the data pointed to by these components.
2176
2177 @item @emph{Example}:
2178 @smallexample
2179    use iso_c_binding
2180    integer(c_int) :: i
2181    real(c_float) :: r, s(5)
2182    print *, (c_sizeof(s)/c_sizeof(r) == 5)
2183    end
2184 @end smallexample
2185 The example will print @code{.TRUE.} unless you are using a platform
2186 where default @code{REAL} variables are unusually padded.
2187
2188 @item @emph{See also}:
2189 @ref{SIZEOF}
2190 @end table
2191
2192
2193 @node CEILING
2194 @section @code{CEILING} --- Integer ceiling function
2195 @fnindex CEILING
2196 @cindex ceiling
2197 @cindex rounding, ceiling
2198
2199 @table @asis
2200 @item @emph{Description}:
2201 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2202
2203 @item @emph{Standard}:
2204 Fortran 95 and later
2205
2206 @item @emph{Class}:
2207 Elemental function
2208
2209 @item @emph{Syntax}:
2210 @code{RESULT = CEILING(A [, KIND])}
2211
2212 @item @emph{Arguments}:
2213 @multitable @columnfractions .15 .70
2214 @item @var{A} @tab The type shall be @code{REAL}.
2215 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2216 expression indicating the kind parameter of the result.
2217 @end multitable
2218
2219 @item @emph{Return value}:
2220 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2221 and a default-kind @code{INTEGER} otherwise.
2222
2223 @item @emph{Example}:
2224 @smallexample
2225 program test_ceiling
2226     real :: x = 63.29
2227     real :: y = -63.59
2228     print *, ceiling(x) ! returns 64
2229     print *, ceiling(y) ! returns -63
2230 end program test_ceiling
2231 @end smallexample
2232
2233 @item @emph{See also}:
2234 @ref{FLOOR}, @ref{NINT}
2235
2236 @end table
2237
2238
2239
2240 @node CHAR
2241 @section @code{CHAR} --- Character conversion function
2242 @fnindex CHAR
2243 @cindex conversion, to character
2244
2245 @table @asis
2246 @item @emph{Description}:
2247 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2248
2249 @item @emph{Standard}:
2250 Fortran 77 and later
2251
2252 @item @emph{Class}:
2253 Elemental function
2254
2255 @item @emph{Syntax}:
2256 @code{RESULT = CHAR(I [, KIND])}
2257
2258 @item @emph{Arguments}:
2259 @multitable @columnfractions .15 .70
2260 @item @var{I} @tab The type shall be @code{INTEGER}.
2261 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2262 expression indicating the kind parameter of the result.
2263 @end multitable
2264
2265 @item @emph{Return value}:
2266 The return value is of type @code{CHARACTER(1)}
2267
2268 @item @emph{Example}:
2269 @smallexample
2270 program test_char
2271     integer :: i = 74
2272     character(1) :: c
2273     c = char(i)
2274     print *, i, c ! returns 'J'
2275 end program test_char
2276 @end smallexample
2277
2278 @item @emph{Note}:
2279 See @ref{ICHAR} for a discussion of converting between numerical values
2280 and formatted string representations.
2281
2282 @item @emph{See also}:
2283 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2284
2285 @end table
2286
2287
2288
2289 @node CHDIR
2290 @section @code{CHDIR} --- Change working directory
2291 @fnindex CHDIR
2292 @cindex system, working directory
2293
2294 @table @asis
2295 @item @emph{Description}:
2296 Change current working directory to a specified path.
2297
2298 This intrinsic is provided in both subroutine and function forms; however,
2299 only one form can be used in any given program unit.
2300
2301 @item @emph{Standard}:
2302 GNU extension
2303
2304 @item @emph{Class}:
2305 Subroutine, function
2306
2307 @item @emph{Syntax}:
2308 @multitable @columnfractions .80
2309 @item @code{CALL CHDIR(NAME [, STATUS])}
2310 @item @code{STATUS = CHDIR(NAME)}
2311 @end multitable
2312
2313 @item @emph{Arguments}:
2314 @multitable @columnfractions .15 .70
2315 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
2316 kind and shall specify a valid path within the file system.
2317 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2318 kind.  Returns 0 on success, and a system specific and nonzero error code
2319 otherwise.
2320 @end multitable
2321
2322 @item @emph{Example}:
2323 @smallexample
2324 PROGRAM test_chdir
2325   CHARACTER(len=255) :: path
2326   CALL getcwd(path)
2327   WRITE(*,*) TRIM(path)
2328   CALL chdir("/tmp")
2329   CALL getcwd(path)
2330   WRITE(*,*) TRIM(path)
2331 END PROGRAM
2332 @end smallexample
2333
2334 @item @emph{See also}:
2335 @ref{GETCWD}
2336 @end table
2337
2338
2339
2340 @node CHMOD
2341 @section @code{CHMOD} --- Change access permissions of files
2342 @fnindex CHMOD
2343 @cindex file system, change access mode
2344
2345 @table @asis
2346 @item @emph{Description}:
2347 @code{CHMOD} changes the permissions of a file. This function invokes
2348 @code{/bin/chmod} and might therefore not work on all platforms.
2349
2350 This intrinsic is provided in both subroutine and function forms; however,
2351 only one form can be used in any given program unit.
2352
2353 @item @emph{Standard}:
2354 GNU extension
2355
2356 @item @emph{Class}:
2357 Subroutine, function
2358
2359 @item @emph{Syntax}:
2360 @multitable @columnfractions .80
2361 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2362 @item @code{STATUS = CHMOD(NAME, MODE)}
2363 @end multitable
2364
2365 @item @emph{Arguments}:
2366 @multitable @columnfractions .15 .70
2367
2368 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2369 file name. Trailing blanks are ignored unless the character
2370 @code{achar(0)} is present, then all characters up to and excluding
2371 @code{achar(0)} are used as the file name.
2372
2373 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2374 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2375 argument of @code{/bin/chmod}.
2376
2377 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2378 @code{0} on success and nonzero otherwise.
2379 @end multitable
2380
2381 @item @emph{Return value}:
2382 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2383 otherwise.
2384
2385 @item @emph{Example}:
2386 @code{CHMOD} as subroutine
2387 @smallexample
2388 program chmod_test
2389   implicit none
2390   integer :: status
2391   call chmod('test.dat','u+x',status)
2392   print *, 'Status: ', status
2393 end program chmod_test
2394 @end smallexample
2395 @code{CHMOD} as function:
2396 @smallexample
2397 program chmod_test
2398   implicit none
2399   integer :: status
2400   status = chmod('test.dat','u+x')
2401   print *, 'Status: ', status
2402 end program chmod_test
2403 @end smallexample
2404
2405 @end table
2406
2407
2408
2409 @node CMPLX
2410 @section @code{CMPLX} --- Complex conversion function
2411 @fnindex CMPLX
2412 @cindex complex numbers, conversion to
2413 @cindex conversion, to complex
2414
2415 @table @asis
2416 @item @emph{Description}:
2417 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2418 the real component.  If @var{Y} is present it is converted to the imaginary
2419 component.  If @var{Y} is not present then the imaginary component is set to
2420 0.0.  If @var{X} is complex then @var{Y} must not be present.
2421
2422 @item @emph{Standard}:
2423 Fortran 77 and later
2424
2425 @item @emph{Class}:
2426 Elemental function
2427
2428 @item @emph{Syntax}:
2429 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2430
2431 @item @emph{Arguments}:
2432 @multitable @columnfractions .15 .70
2433 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2434 or @code{COMPLEX}.
2435 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2436 @code{COMPLEX}.)  May be @code{INTEGER} or @code{REAL}.
2437 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2438 expression indicating the kind parameter of the result.
2439 @end multitable
2440
2441 @item @emph{Return value}:
2442 The return value is of @code{COMPLEX} type, with a kind equal to
2443 @var{KIND} if it is specified.  If @var{KIND} is not specified, the
2444 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2445 @var{X} and @var{Y}. 
2446
2447 @item @emph{Example}:
2448 @smallexample
2449 program test_cmplx
2450     integer :: i = 42
2451     real :: x = 3.14
2452     complex :: z
2453     z = cmplx(i, x)
2454     print *, z, cmplx(x)
2455 end program test_cmplx
2456 @end smallexample
2457
2458 @item @emph{See also}:
2459 @ref{COMPLEX}
2460 @end table
2461
2462
2463
2464 @node COMMAND_ARGUMENT_COUNT
2465 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2466 @fnindex COMMAND_ARGUMENT_COUNT
2467 @cindex command-line arguments
2468 @cindex command-line arguments, number of
2469 @cindex arguments, to program
2470
2471 @table @asis
2472 @item @emph{Description}:
2473 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2474 command line when the containing program was invoked.
2475
2476 @item @emph{Standard}:
2477 Fortran 2003 and later
2478
2479 @item @emph{Class}:
2480 Inquiry function
2481
2482 @item @emph{Syntax}:
2483 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2484
2485 @item @emph{Arguments}:
2486 @multitable @columnfractions .15 .70
2487 @item None
2488 @end multitable
2489
2490 @item @emph{Return value}:
2491 The return value is an @code{INTEGER} of default kind.
2492
2493 @item @emph{Example}:
2494 @smallexample
2495 program test_command_argument_count
2496     integer :: count
2497     count = command_argument_count()
2498     print *, count
2499 end program test_command_argument_count
2500 @end smallexample
2501
2502 @item @emph{See also}:
2503 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2504 @end table
2505
2506
2507
2508 @node COMPLEX
2509 @section @code{COMPLEX} --- Complex conversion function
2510 @fnindex COMPLEX
2511 @cindex complex numbers, conversion to
2512 @cindex conversion, to complex
2513
2514 @table @asis
2515 @item @emph{Description}:
2516 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2517 to the real component and @var{Y} is converted to the imaginary
2518 component.
2519
2520 @item @emph{Standard}:
2521 GNU extension
2522
2523 @item @emph{Class}:
2524 Elemental function
2525
2526 @item @emph{Syntax}:
2527 @code{RESULT = COMPLEX(X, Y)}
2528
2529 @item @emph{Arguments}:
2530 @multitable @columnfractions .15 .70
2531 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2532 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2533 @end multitable
2534
2535 @item @emph{Return value}:
2536 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2537 value is of default @code{COMPLEX} type.
2538
2539 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2540 type and one is of @code{INTEGER} type, then the return value is of
2541 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2542 argument with the highest precision.  
2543
2544 @item @emph{Example}:
2545 @smallexample
2546 program test_complex
2547     integer :: i = 42
2548     real :: x = 3.14
2549     print *, complex(i, x)
2550 end program test_complex
2551 @end smallexample
2552
2553 @item @emph{See also}:
2554 @ref{CMPLX}
2555 @end table
2556
2557
2558
2559 @node CONJG
2560 @section @code{CONJG} --- Complex conjugate function 
2561 @fnindex CONJG
2562 @fnindex DCONJG
2563 @cindex complex conjugate
2564
2565 @table @asis
2566 @item @emph{Description}:
2567 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2568 then the result is @code{(x, -y)}
2569
2570 @item @emph{Standard}:
2571 Fortran 77 and later, has overloads that are GNU extensions
2572
2573 @item @emph{Class}:
2574 Elemental function
2575
2576 @item @emph{Syntax}:
2577 @code{Z = CONJG(Z)}
2578
2579 @item @emph{Arguments}:
2580 @multitable @columnfractions .15 .70
2581 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2582 @end multitable
2583
2584 @item @emph{Return value}:
2585 The return value is of type @code{COMPLEX}.
2586
2587 @item @emph{Example}:
2588 @smallexample
2589 program test_conjg
2590     complex :: z = (2.0, 3.0)
2591     complex(8) :: dz = (2.71_8, -3.14_8)
2592     z= conjg(z)
2593     print *, z
2594     dz = dconjg(dz)
2595     print *, dz
2596 end program test_conjg
2597 @end smallexample
2598
2599 @item @emph{Specific names}:
2600 @multitable @columnfractions .20 .20 .20 .25
2601 @item Name             @tab Argument             @tab Return type          @tab Standard
2602 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)}    @tab GNU extension
2603 @end multitable
2604 @end table
2605
2606
2607
2608 @node COS
2609 @section @code{COS} --- Cosine function 
2610 @fnindex COS
2611 @fnindex DCOS
2612 @fnindex CCOS
2613 @fnindex ZCOS
2614 @fnindex CDCOS
2615 @cindex trigonometric function, cosine
2616 @cindex cosine
2617
2618 @table @asis
2619 @item @emph{Description}:
2620 @code{COS(X)} computes the cosine of @var{X}.
2621
2622 @item @emph{Standard}:
2623 Fortran 77 and later, has overloads that are GNU extensions
2624
2625 @item @emph{Class}:
2626 Elemental function
2627
2628 @item @emph{Syntax}:
2629 @code{RESULT = COS(X)}
2630
2631 @item @emph{Arguments}:
2632 @multitable @columnfractions .15 .70
2633 @item @var{X} @tab The type shall be @code{REAL} or
2634 @code{COMPLEX}.
2635 @end multitable
2636
2637 @item @emph{Return value}:
2638 The return value is of type @code{REAL} and it lies in the
2639 range @math{ -1 \leq \cos (x) \leq 1}.  The kind type
2640 parameter is the same as @var{X}.
2641
2642 @item @emph{Example}:
2643 @smallexample
2644 program test_cos
2645   real :: x = 0.0
2646   x = cos(x)
2647 end program test_cos
2648 @end smallexample
2649
2650 @item @emph{Specific names}:
2651 @multitable @columnfractions .20 .20 .20 .25
2652 @item Name            @tab Argument            @tab Return type       @tab Standard
2653 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
2654 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2655 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2656 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2657 @end multitable
2658
2659 @item @emph{See also}:
2660 Inverse function: @ref{ACOS}
2661
2662 @end table
2663
2664
2665
2666 @node COSH
2667 @section @code{COSH} --- Hyperbolic cosine function 
2668 @fnindex COSH
2669 @fnindex DCOSH
2670 @cindex hyperbolic cosine
2671 @cindex hyperbolic function, cosine
2672 @cindex cosine, hyperbolic
2673
2674 @table @asis
2675 @item @emph{Description}:
2676 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2677
2678 @item @emph{Standard}:
2679 Fortran 77 and later
2680
2681 @item @emph{Class}:
2682 Elemental function
2683
2684 @item @emph{Syntax}:
2685 @code{X = COSH(X)}
2686
2687 @item @emph{Arguments}:
2688 @multitable @columnfractions .15 .70
2689 @item @var{X} @tab The type shall be @code{REAL}.
2690 @end multitable
2691
2692 @item @emph{Return value}:
2693 The return value is of type @code{REAL} and it is positive
2694 (@math{ \cosh (x) \geq 0 }).  For a @code{REAL} argument @var{X},
2695 @math{ \cosh (x) \geq 1 }.
2696 The return value is of the same kind as @var{X}.
2697
2698 @item @emph{Example}:
2699 @smallexample
2700 program test_cosh
2701   real(8) :: x = 1.0_8
2702   x = cosh(x)
2703 end program test_cosh
2704 @end smallexample
2705
2706 @item @emph{Specific names}:
2707 @multitable @columnfractions .20 .20 .20 .25
2708 @item Name            @tab Argument          @tab Return type       @tab Standard
2709 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
2710 @end multitable
2711
2712 @item @emph{See also}:
2713 Inverse function: @ref{ACOSH}
2714
2715 @end table
2716
2717
2718
2719 @node COUNT
2720 @section @code{COUNT} --- Count function
2721 @fnindex COUNT
2722 @cindex array, conditionally count elements
2723 @cindex array, element counting
2724 @cindex array, number of elements
2725
2726 @table @asis
2727 @item @emph{Description}:
2728
2729 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2730 elements of @var{MASK} along the dimension of @var{DIM}.  If @var{DIM} is
2731 omitted it is taken to be @code{1}.  @var{DIM} is a scalar of type
2732 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2733 is the rank of @var{MASK}.
2734
2735 @item @emph{Standard}:
2736 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2737
2738 @item @emph{Class}:
2739 Transformational function
2740
2741 @item @emph{Syntax}:
2742 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2743
2744 @item @emph{Arguments}:
2745 @multitable @columnfractions .15 .70
2746 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2747 @item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
2748 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2749 expression indicating the kind parameter of the result.
2750 @end multitable
2751
2752 @item @emph{Return value}:
2753 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2754 @var{KIND} is absent, the return value is of default integer kind.
2755 The result has a rank equal to that of @var{MASK}.
2756
2757 @item @emph{Example}:
2758 @smallexample
2759 program test_count
2760     integer, dimension(2,3) :: a, b
2761     logical, dimension(2,3) :: mask
2762     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2763     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2764     print '(3i3)', a(1,:)
2765     print '(3i3)', a(2,:)
2766     print *
2767     print '(3i3)', b(1,:)
2768     print '(3i3)', b(2,:)
2769     print *
2770     mask = a.ne.b
2771     print '(3l3)', mask(1,:)
2772     print '(3l3)', mask(2,:)
2773     print *
2774     print '(3i3)', count(mask)
2775     print *
2776     print '(3i3)', count(mask, 1)
2777     print *
2778     print '(3i3)', count(mask, 2)
2779 end program test_count
2780 @end smallexample
2781 @end table
2782
2783
2784
2785 @node CPU_TIME
2786 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2787 @fnindex CPU_TIME
2788 @cindex time, elapsed
2789
2790 @table @asis
2791 @item @emph{Description}:
2792 Returns a @code{REAL} value representing the elapsed CPU time in
2793 seconds.  This is useful for testing segments of code to determine
2794 execution time.
2795
2796 If a time source is available, time will be reported with microsecond
2797 resolution. If no time source is available, @var{TIME} is set to
2798 @code{-1.0}.
2799
2800 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2801 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2802 value is meaningless, only differences between subsequent calls to
2803 this subroutine, as shown in the example below, should be used.
2804
2805
2806 @item @emph{Standard}:
2807 Fortran 95 and later
2808
2809 @item @emph{Class}:
2810 Subroutine
2811
2812 @item @emph{Syntax}:
2813 @code{CALL CPU_TIME(TIME)}
2814
2815 @item @emph{Arguments}:
2816 @multitable @columnfractions .15 .70
2817 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2818 @end multitable
2819
2820 @item @emph{Return value}:
2821 None
2822
2823 @item @emph{Example}:
2824 @smallexample
2825 program test_cpu_time
2826     real :: start, finish
2827     call cpu_time(start)
2828         ! put code to test here
2829     call cpu_time(finish)
2830     print '("Time = ",f6.3," seconds.")',finish-start
2831 end program test_cpu_time
2832 @end smallexample
2833
2834 @item @emph{See also}:
2835 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2836 @end table
2837
2838
2839
2840 @node CSHIFT
2841 @section @code{CSHIFT} --- Circular shift elements of an array
2842 @fnindex CSHIFT
2843 @cindex array, shift circularly
2844 @cindex array, permutation
2845 @cindex array, rotate
2846
2847 @table @asis
2848 @item @emph{Description}:
2849 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2850 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
2851 taken to be @code{1}.  @var{DIM} is a scalar of type @code{INTEGER} in the
2852 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2853 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2854 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
2855 sections of @var{ARRAY} along the given dimension are shifted.  Elements
2856 shifted out one end of each rank one section are shifted back in the other end.
2857
2858 @item @emph{Standard}:
2859 Fortran 95 and later
2860
2861 @item @emph{Class}:
2862 Transformational function
2863
2864 @item @emph{Syntax}:
2865 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2866
2867 @item @emph{Arguments}:
2868 @multitable @columnfractions .15 .70
2869 @item @var{ARRAY}  @tab Shall be an array of any type.
2870 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
2871 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
2872 @end multitable
2873
2874 @item @emph{Return value}:
2875 Returns an array of same type and rank as the @var{ARRAY} argument.
2876
2877 @item @emph{Example}:
2878 @smallexample
2879 program test_cshift
2880     integer, dimension(3,3) :: a
2881     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2882     print '(3i3)', a(1,:)
2883     print '(3i3)', a(2,:)
2884     print '(3i3)', a(3,:)    
2885     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2886     print *
2887     print '(3i3)', a(1,:)
2888     print '(3i3)', a(2,:)
2889     print '(3i3)', a(3,:)
2890 end program test_cshift
2891 @end smallexample
2892 @end table
2893
2894
2895
2896 @node CTIME
2897 @section @code{CTIME} --- Convert a time into a string
2898 @fnindex CTIME
2899 @cindex time, conversion to string
2900 @cindex conversion, to string
2901
2902 @table @asis
2903 @item @emph{Description}:
2904 @code{CTIME} converts a system time value, such as returned by
2905 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2906
2907 This intrinsic is provided in both subroutine and function forms; however,
2908 only one form can be used in any given program unit.
2909
2910 @item @emph{Standard}:
2911 GNU extension
2912
2913 @item @emph{Class}:
2914 Subroutine, function
2915
2916 @item @emph{Syntax}:
2917 @multitable @columnfractions .80
2918 @item @code{CALL CTIME(TIME, RESULT)}.
2919 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2920 @end multitable
2921
2922 @item @emph{Arguments}:
2923 @multitable @columnfractions .15 .70
2924 @item @var{TIME}    @tab The type shall be of type @code{INTEGER(KIND=8)}.
2925 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
2926 of default kind.
2927 @end multitable
2928
2929 @item @emph{Return value}:
2930 The converted date and time as a string.
2931
2932 @item @emph{Example}:
2933 @smallexample
2934 program test_ctime
2935     integer(8) :: i
2936     character(len=30) :: date
2937     i = time8()
2938
2939     ! Do something, main part of the program
2940     
2941     call ctime(i,date)
2942     print *, 'Program was started on ', date
2943 end program test_ctime
2944 @end smallexample
2945
2946 @item @emph{See Also}:
2947 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2948 @end table
2949
2950
2951
2952 @node DATE_AND_TIME
2953 @section @code{DATE_AND_TIME} --- Date and time subroutine
2954 @fnindex DATE_AND_TIME
2955 @cindex date, current
2956 @cindex current date
2957 @cindex time, current
2958 @cindex current time
2959
2960 @table @asis
2961 @item @emph{Description}:
2962 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2963 time information from the real-time system clock.  @var{DATE} is
2964 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
2965 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2966 representing the difference with respect to Coordinated Universal Time (UTC).
2967 Unavailable time and date parameters return blanks.
2968
2969 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2970
2971 @multitable @columnfractions .15 .30 .40
2972 @item @tab @code{VALUE(1)}: @tab The year
2973 @item @tab @code{VALUE(2)}: @tab The month
2974 @item @tab @code{VALUE(3)}: @tab The day of the month
2975 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2976 @item @tab @code{VALUE(5)}: @tab The hour of the day
2977 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2978 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2979 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2980 @end multitable
2981
2982 @item @emph{Standard}:
2983 Fortran 95 and later
2984
2985 @item @emph{Class}:
2986 Subroutine
2987
2988 @item @emph{Syntax}:
2989 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2990
2991 @item @emph{Arguments}:
2992 @multitable @columnfractions .15 .70
2993 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
2994 or larger, and of default kind.
2995 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
2996 or larger, and of default kind.
2997 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
2998 or larger, and of default kind.
2999 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3000 @end multitable
3001
3002 @item @emph{Return value}:
3003 None
3004
3005 @item @emph{Example}:
3006 @smallexample
3007 program test_time_and_date
3008     character(8)  :: date
3009     character(10) :: time
3010     character(5)  :: zone
3011     integer,dimension(8) :: values
3012     ! using keyword arguments
3013     call date_and_time(date,time,zone,values)
3014     call date_and_time(DATE=date,ZONE=zone)
3015     call date_and_time(TIME=time)
3016     call date_and_time(VALUES=values)
3017     print '(a,2x,a,2x,a)', date, time, zone
3018     print '(8i5))', values
3019 end program test_time_and_date
3020 @end smallexample
3021
3022 @item @emph{See also}:
3023 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3024 @end table
3025
3026
3027
3028 @node DBLE
3029 @section @code{DBLE} --- Double conversion function 
3030 @fnindex DBLE
3031 @cindex conversion, to real
3032
3033 @table @asis
3034 @item @emph{Description}:
3035 @code{DBLE(A)} Converts @var{A} to double precision real type.
3036
3037 @item @emph{Standard}:
3038 Fortran 77 and later
3039
3040 @item @emph{Class}:
3041 Elemental function
3042
3043 @item @emph{Syntax}:
3044 @code{RESULT = DBLE(A)}
3045
3046 @item @emph{Arguments}:
3047 @multitable @columnfractions .15 .70
3048 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3049 or @code{COMPLEX}.
3050 @end multitable
3051
3052 @item @emph{Return value}:
3053 The return value is of type double precision real.
3054
3055 @item @emph{Example}:
3056 @smallexample
3057 program test_dble
3058     real    :: x = 2.18
3059     integer :: i = 5
3060     complex :: z = (2.3,1.14)
3061     print *, dble(x), dble(i), dble(z)
3062 end program test_dble
3063 @end smallexample
3064
3065 @item @emph{See also}:
3066 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3067 @end table
3068
3069
3070
3071 @node DCMPLX
3072 @section @code{DCMPLX} --- Double complex conversion function
3073 @fnindex DCMPLX
3074 @cindex complex numbers, conversion to
3075 @cindex conversion, to complex
3076
3077 @table @asis
3078 @item @emph{Description}:
3079 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3080 converted to the real component.  If @var{Y} is present it is converted to the
3081 imaginary component.  If @var{Y} is not present then the imaginary component is
3082 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3083
3084 @item @emph{Standard}:
3085 GNU extension
3086
3087 @item @emph{Class}:
3088 Elemental function
3089
3090 @item @emph{Syntax}:
3091 @code{RESULT = DCMPLX(X [, Y])}
3092
3093 @item @emph{Arguments}:
3094 @multitable @columnfractions .15 .70
3095 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3096 or @code{COMPLEX}.
3097 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3098 @code{INTEGER} or @code{REAL}. 
3099 @end multitable
3100
3101 @item @emph{Return value}:
3102 The return value is of type @code{COMPLEX(8)}
3103
3104 @item @emph{Example}:
3105 @smallexample
3106 program test_dcmplx
3107     integer :: i = 42
3108     real :: x = 3.14
3109     complex :: z
3110     z = cmplx(i, x)
3111     print *, dcmplx(i)
3112     print *, dcmplx(x)
3113     print *, dcmplx(z)
3114     print *, dcmplx(x,i)
3115 end program test_dcmplx
3116 @end smallexample
3117 @end table
3118
3119
3120
3121 @node DFLOAT
3122 @section @code{DFLOAT} --- Double conversion function 
3123 @fnindex DFLOAT
3124 @cindex conversion, to real
3125
3126 @table @asis
3127 @item @emph{Description}:
3128 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3129
3130 @item @emph{Standard}:
3131 GNU extension
3132
3133 @item @emph{Class}:
3134 Elemental function
3135
3136 @item @emph{Syntax}:
3137 @code{RESULT = DFLOAT(A)}
3138
3139 @item @emph{Arguments}:
3140 @multitable @columnfractions .15 .70
3141 @item @var{A} @tab The type shall be @code{INTEGER}.
3142 @end multitable
3143
3144 @item @emph{Return value}:
3145 The return value is of type double precision real.
3146
3147 @item @emph{Example}:
3148 @smallexample
3149 program test_dfloat
3150     integer :: i = 5
3151     print *, dfloat(i)
3152 end program test_dfloat
3153 @end smallexample
3154
3155 @item @emph{See also}:
3156 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3157 @end table
3158
3159
3160
3161 @node DIGITS
3162 @section @code{DIGITS} --- Significant binary digits function
3163 @fnindex DIGITS
3164 @cindex model representation, significant digits
3165
3166 @table @asis
3167 @item @emph{Description}:
3168 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3169 model representation of @var{X}.  For example, on a system using a 32-bit
3170 floating point representation, a default real number would likely return 24.
3171
3172 @item @emph{Standard}:
3173 Fortran 95 and later
3174
3175 @item @emph{Class}:
3176 Inquiry function
3177
3178 @item @emph{Syntax}:
3179 @code{RESULT = DIGITS(X)}
3180
3181 @item @emph{Arguments}:
3182 @multitable @columnfractions .15 .70
3183 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3184 @end multitable
3185
3186 @item @emph{Return value}:
3187 The return value is of type @code{INTEGER}.
3188
3189 @item @emph{Example}:
3190 @smallexample
3191 program test_digits
3192     integer :: i = 12345
3193     real :: x = 3.143
3194     real(8) :: y = 2.33
3195     print *, digits(i)
3196     print *, digits(x)
3197     print *, digits(y)
3198 end program test_digits
3199 @end smallexample
3200 @end table
3201
3202
3203
3204 @node DIM
3205 @section @code{DIM} --- Positive difference
3206 @fnindex DIM
3207 @fnindex IDIM
3208 @fnindex DDIM
3209 @cindex positive difference
3210
3211 @table @asis
3212 @item @emph{Description}:
3213 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3214 otherwise returns zero.
3215
3216 @item @emph{Standard}:
3217 Fortran 77 and later
3218
3219 @item @emph{Class}:
3220 Elemental function
3221
3222 @item @emph{Syntax}:
3223 @code{RESULT = DIM(X, Y)}
3224
3225 @item @emph{Arguments}:
3226 @multitable @columnfractions .15 .70
3227 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3228 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3229 @end multitable
3230
3231 @item @emph{Return value}:
3232 The return value is of type @code{INTEGER} or @code{REAL}.
3233
3234 @item @emph{Example}:
3235 @smallexample
3236 program test_dim
3237     integer :: i
3238     real(8) :: x
3239     i = dim(4, 15)
3240     x = dim(4.345_8, 2.111_8)
3241     print *, i
3242     print *, x
3243 end program test_dim
3244 @end smallexample
3245
3246 @item @emph{Specific names}:
3247 @multitable @columnfractions .20 .20 .20 .25
3248 @item Name             @tab Argument              @tab Return type       @tab Standard
3249 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3250 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3251 @end multitable
3252 @end table
3253
3254
3255
3256 @node DOT_PRODUCT
3257 @section @code{DOT_PRODUCT} --- Dot product function
3258 @fnindex DOT_PRODUCT
3259 @cindex dot product
3260 @cindex vector product
3261 @cindex product, vector
3262
3263 @table @asis
3264 @item @emph{Description}:
3265 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3266 of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
3267 either numeric or logical and must be arrays of rank one and of equal size. If
3268 the vectors are @code{INTEGER} or @code{REAL}, the result is
3269 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3270 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3271 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.  
3272
3273 @item @emph{Standard}:
3274 Fortran 95 and later
3275
3276 @item @emph{Class}:
3277 Transformational function
3278
3279 @item @emph{Syntax}:
3280 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3281
3282 @item @emph{Arguments}:
3283 @multitable @columnfractions .15 .70
3284 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3285 @item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array.
3286 @end multitable
3287
3288 @item @emph{Return value}:
3289 If the arguments are numeric, the return value is a scalar of numeric type,
3290 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
3291 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3292
3293 @item @emph{Example}:
3294 @smallexample
3295 program test_dot_prod
3296     integer, dimension(3) :: a, b
3297     a = (/ 1, 2, 3 /)
3298     b = (/ 4, 5, 6 /)
3299     print '(3i3)', a
3300     print *
3301     print '(3i3)', b
3302     print *
3303     print *, dot_product(a,b)
3304 end program test_dot_prod
3305 @end smallexample
3306 @end table
3307
3308
3309
3310 @node DPROD
3311 @section @code{DPROD} --- Double product function
3312 @fnindex DPROD
3313 @cindex product, double-precision
3314
3315 @table @asis
3316 @item @emph{Description}:
3317 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3318
3319 @item @emph{Standard}:
3320 Fortran 77 and later
3321
3322 @item @emph{Class}:
3323 Elemental function
3324
3325 @item @emph{Syntax}:
3326 @code{RESULT = DPROD(X, Y)}
3327
3328 @item @emph{Arguments}:
3329 @multitable @columnfractions .15 .70
3330 @item @var{X} @tab The type shall be @code{REAL}.
3331 @item @var{Y} @tab The type shall be @code{REAL}.
3332 @end multitable
3333
3334 @item @emph{Return value}:
3335 The return value is of type @code{REAL(8)}.
3336
3337 @item @emph{Example}:
3338 @smallexample
3339 program test_dprod
3340     real :: x = 5.2
3341     real :: y = 2.3
3342     real(8) :: d
3343     d = dprod(x,y)
3344     print *, d
3345 end program test_dprod
3346 @end smallexample
3347 @end table
3348
3349
3350
3351 @node DREAL
3352 @section @code{DREAL} --- Double real part function
3353 @fnindex DREAL
3354 @cindex complex numbers, real part
3355
3356 @table @asis
3357 @item @emph{Description}:
3358 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3359
3360 @item @emph{Standard}:
3361 GNU extension
3362
3363 @item @emph{Class}:
3364 Elemental function
3365
3366 @item @emph{Syntax}:
3367 @code{RESULT = DREAL(A)}
3368
3369 @item @emph{Arguments}:
3370 @multitable @columnfractions .15 .70
3371 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3372 @end multitable
3373
3374 @item @emph{Return value}:
3375 The return value is of type @code{REAL(8)}.
3376
3377 @item @emph{Example}:
3378 @smallexample
3379 program test_dreal
3380     complex(8) :: z = (1.3_8,7.2_8)
3381     print *, dreal(z)
3382 end program test_dreal
3383 @end smallexample
3384
3385 @item @emph{See also}:
3386 @ref{AIMAG}
3387
3388 @end table
3389
3390
3391
3392 @node DTIME
3393 @section @code{DTIME} --- Execution time subroutine (or function)
3394 @fnindex DTIME
3395 @cindex time, elapsed
3396 @cindex elapsed time
3397
3398 @table @asis
3399 @item @emph{Description}:
3400 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3401 since the start of the process's execution in @var{TIME}.  @var{VALUES}
3402 returns the user and system components of this time in @code{VALUES(1)} and
3403 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3404 VALUES(2)}.
3405
3406 Subsequent invocations of @code{DTIME} return values accumulated since the
3407 previous invocation.
3408
3409 On some systems, the underlying timings are represented using types with
3410 sufficiently small limits that overflows (wrap around) are possible, such as
3411 32-bit types. Therefore, the values returned by this intrinsic might be, or
3412 become, negative, or numerically less than previous values, during a single
3413 run of the compiled program.
3414
3415 Please note, that this implementation is thread safe if used within OpenMP
3416 directives, i.e., its state will be consistent while called from multiple
3417 threads. However, if @code{DTIME} is called from multiple threads, the result
3418 is still the time since the last invocation. This may not give the intended
3419 results. If possible, use @code{CPU_TIME} instead.
3420
3421 This intrinsic is provided in both subroutine and function forms; however,
3422 only one form can be used in any given program unit.
3423
3424 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3425
3426 @multitable @columnfractions .15 .30 .40
3427 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3428 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3429 @item @tab @code{TIME}: @tab Run time since start in seconds.
3430 @end multitable
3431
3432 @item @emph{Standard}:
3433 GNU extension
3434
3435 @item @emph{Class}:
3436 Subroutine, function
3437
3438 @item @emph{Syntax}:
3439 @multitable @columnfractions .80
3440 @item @code{CALL DTIME(VALUES, TIME)}.
3441 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3442 @end multitable
3443
3444 @item @emph{Arguments}:
3445 @multitable @columnfractions .15 .70
3446 @item @var{VALUES}@tab The type shall be @code{REAL, DIMENSION(2)}.
3447 @item @var{TIME}@tab The type shall be @code{REAL}.
3448 @end multitable
3449
3450 @item @emph{Return value}:
3451 Elapsed time in seconds since the last invocation or since the start of program
3452 execution if not called before.
3453
3454 @item @emph{Example}:
3455 @smallexample
3456 program test_dtime
3457     integer(8) :: i, j
3458     real, dimension(2) :: tarray
3459     real :: result
3460     call dtime(tarray, result)
3461     print *, result
3462     print *, tarray(1)
3463     print *, tarray(2)   
3464     do i=1,100000000    ! Just a delay
3465         j = i * i - i
3466     end do
3467     call dtime(tarray, result)
3468     print *, result
3469     print *, tarray(1)
3470     print *, tarray(2)
3471 end program test_dtime
3472 @end smallexample
3473
3474 @item @emph{See also}:
3475 @ref{CPU_TIME}
3476
3477 @end table
3478
3479
3480
3481 @node EOSHIFT
3482 @section @code{EOSHIFT} --- End-off shift elements of an array
3483 @fnindex EOSHIFT
3484 @cindex array, shift
3485
3486 @table @asis
3487 @item @emph{Description}:
3488 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3489 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3490 omitted it is taken to be @code{1}.  @var{DIM} is a scalar of type
3491 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3492 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3493 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3494 then all complete rank one sections of @var{ARRAY} along the given dimension are
3495 shifted.  Elements shifted out one end of each rank one section are dropped.  If
3496 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3497 is copied back in the other end.  If @var{BOUNDARY} is not present then the
3498 following are copied in depending on the type of @var{ARRAY}.
3499
3500 @multitable @columnfractions .15 .80
3501 @item @emph{Array Type} @tab @emph{Boundary Value}
3502 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3503 @item Logical  @tab @code{.FALSE.}.
3504 @item Character(@var{len}) @tab @var{len} blanks.
3505 @end multitable
3506
3507 @item @emph{Standard}:
3508 Fortran 95 and later
3509
3510 @item @emph{Class}:
3511 Transformational function
3512
3513 @item @emph{Syntax}:
3514 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3515
3516 @item @emph{Arguments}:
3517 @multitable @columnfractions .15 .70
3518 @item @var{ARRAY}  @tab May be any type, not scalar.
3519 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3520 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}. 
3521 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3522 @end multitable
3523
3524 @item @emph{Return value}:
3525 Returns an array of same type and rank as the @var{ARRAY} argument.
3526
3527 @item @emph{Example}:
3528 @smallexample
3529 program test_eoshift
3530     integer, dimension(3,3) :: a
3531     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3532     print '(3i3)', a(1,:)
3533     print '(3i3)', a(2,:)
3534     print '(3i3)', a(3,:)    
3535     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3536     print *
3537     print '(3i3)', a(1,:)
3538     print '(3i3)', a(2,:)
3539     print '(3i3)', a(3,:)
3540 end program test_eoshift
3541 @end smallexample
3542 @end table
3543
3544
3545
3546 @node EPSILON
3547 @section @code{EPSILON} --- Epsilon function
3548 @fnindex EPSILON
3549 @cindex model representation, epsilon
3550
3551 @table @asis
3552 @item @emph{Description}:
3553 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3554 as @var{X} such that @math{1 + E > 1}.
3555
3556 @item @emph{Standard}:
3557 Fortran 95 and later
3558
3559 @item @emph{Class}:
3560 Inquiry function
3561
3562 @item @emph{Syntax}:
3563 @code{RESULT = EPSILON(X)}
3564
3565 @item @emph{Arguments}:
3566 @multitable @columnfractions .15 .70
3567 @item @var{X} @tab The type shall be @code{REAL}.
3568 @end multitable
3569
3570 @item @emph{Return value}:
3571 The return value is of same type as the argument.
3572
3573 @item @emph{Example}:
3574 @smallexample
3575 program test_epsilon
3576     real :: x = 3.143
3577     real(8) :: y = 2.33
3578     print *, EPSILON(x)
3579     print *, EPSILON(y)
3580 end program test_epsilon
3581 @end smallexample
3582 @end table
3583
3584
3585
3586 @node ERF
3587 @section @code{ERF} --- Error function 
3588 @fnindex ERF
3589 @cindex error function
3590
3591 @table @asis
3592 @item @emph{Description}:
3593 @code{ERF(X)} computes the error function of @var{X}.
3594
3595 @item @emph{Standard}:
3596 Fortran 2008 and later
3597
3598 @item @emph{Class}:
3599 Elemental function
3600
3601 @item @emph{Syntax}:
3602 @code{RESULT = ERF(X)}
3603
3604 @item @emph{Arguments}:
3605 @multitable @columnfractions .15 .70
3606 @item @var{X} @tab The type shall be @code{REAL}.
3607 @end multitable
3608
3609 @item @emph{Return value}:
3610 The return value is of type @code{REAL}, of the same kind as
3611 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3612
3613 @item @emph{Example}:
3614 @smallexample
3615 program test_erf
3616   real(8) :: x = 0.17_8
3617   x = erf(x)
3618 end program test_erf
3619 @end smallexample
3620
3621 @item @emph{Specific names}:
3622 @multitable @columnfractions .20 .20 .20 .25
3623 @item Name            @tab Argument          @tab Return type       @tab Standard
3624 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3625 @end multitable
3626 @end table
3627
3628
3629
3630 @node ERFC
3631 @section @code{ERFC} --- Error function 
3632 @fnindex ERFC
3633 @cindex error function, complementary
3634
3635 @table @asis
3636 @item @emph{Description}:
3637 @code{ERFC(X)} computes the complementary error function of @var{X}.
3638
3639 @item @emph{Standard}:
3640 Fortran 2008 and later
3641
3642 @item @emph{Class}:
3643 Elemental function
3644
3645 @item @emph{Syntax}:
3646 @code{RESULT = ERFC(X)}
3647
3648 @item @emph{Arguments}:
3649 @multitable @columnfractions .15 .70
3650 @item @var{X} @tab The type shall be @code{REAL}.
3651 @end multitable
3652
3653 @item @emph{Return value}:
3654 The return value is of type @code{REAL} and of the same kind as @var{X}.
3655 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3656
3657 @item @emph{Example}:
3658 @smallexample
3659 program test_erfc
3660   real(8) :: x = 0.17_8
3661   x = erfc(x)
3662 end program test_erfc
3663 @end smallexample
3664
3665 @item @emph{Specific names}:
3666 @multitable @columnfractions .20 .20 .20 .25
3667 @item Name            @tab Argument          @tab Return type       @tab Standard
3668 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3669 @end multitable
3670 @end table
3671
3672
3673
3674 @node ERFC_SCALED
3675 @section @code{ERFC_SCALED} --- Error function 
3676 @fnindex ERFC_SCALED
3677 @cindex error function, complementary, exponentially-scaled
3678
3679 @table @asis
3680 @item @emph{Description}:
3681 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3682 error function of @var{X}.
3683
3684 @item @emph{Standard}:
3685 Fortran 2008 and later
3686
3687 @item @emph{Class}:
3688 Elemental function
3689
3690 @item @emph{Syntax}:
3691 @code{RESULT = ERFC_SCALED(X)}
3692
3693 @item @emph{Arguments}:
3694 @multitable @columnfractions .15 .70
3695 @item @var{X} @tab The type shall be @code{REAL}.
3696 @end multitable
3697
3698 @item @emph{Return value}:
3699 The return value is of type @code{REAL} and of the same kind as @var{X}.
3700
3701 @item @emph{Example}:
3702 @smallexample
3703 program test_erfc_scaled
3704   real(8) :: x = 0.17_8
3705   x = erfc_scaled(x)
3706 end program test_erfc_scaled
3707 @end smallexample
3708 @end table
3709
3710
3711
3712 @node ETIME
3713 @section @code{ETIME} --- Execution time subroutine (or function)
3714 @fnindex ETIME
3715 @cindex time, elapsed
3716
3717 @table @asis
3718 @item @emph{Description}:
3719 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3720 since the start of the process's execution in @var{TIME}.  @var{VALUES}
3721 returns the user and system components of this time in @code{VALUES(1)} and
3722 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3723
3724 On some systems, the underlying timings are represented using types with
3725 sufficiently small limits that overflows (wrap around) are possible, such as
3726 32-bit types. Therefore, the values returned by this intrinsic might be, or
3727 become, negative, or numerically less than previous values, during a single
3728 run of the compiled program.
3729
3730 This intrinsic is provided in both subroutine and function forms; however,
3731 only one form can be used in any given program unit.
3732
3733 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3734
3735 @multitable @columnfractions .15 .30 .60
3736 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3737 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3738 @item @tab @code{TIME}: @tab Run time since start in seconds.
3739 @end multitable
3740
3741 @item @emph{Standard}:
3742 GNU extension
3743
3744 @item @emph{Class}:
3745 Subroutine, function
3746
3747 @item @emph{Syntax}:
3748 @multitable @columnfractions .80
3749 @item @code{CALL ETIME(VALUES, TIME)}.
3750 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3751 @end multitable
3752
3753 @item @emph{Arguments}:
3754 @multitable @columnfractions .15 .70
3755 @item @var{VALUES}@tab The type shall be @code{REAL, DIMENSION(2)}.
3756 @item @var{TIME}@tab The type shall be @code{REAL}.
3757 @end multitable
3758
3759 @item @emph{Return value}:
3760 Elapsed time in seconds since the start of program execution.
3761
3762 @item @emph{Example}:
3763 @smallexample
3764 program test_etime
3765     integer(8) :: i, j
3766     real, dimension(2) :: tarray
3767     real :: result
3768     call ETIME(tarray, result)
3769     print *, result
3770     print *, tarray(1)
3771     print *, tarray(2)   
3772     do i=1,100000000    ! Just a delay
3773         j = i * i - i
3774     end do
3775     call ETIME(tarray, result)
3776     print *, result
3777     print *, tarray(1)
3778     print *, tarray(2)
3779 end program test_etime
3780 @end smallexample
3781
3782 @item @emph{See also}:
3783 @ref{CPU_TIME}
3784
3785 @end table
3786
3787
3788
3789 @node EXIT
3790 @section @code{EXIT} --- Exit the program with status. 
3791 @fnindex EXIT
3792 @cindex program termination
3793 @cindex terminate program
3794
3795 @table @asis
3796 @item @emph{Description}:
3797 @code{EXIT} causes immediate termination of the program with status.  If status
3798 is omitted it returns the canonical @emph{success} for the system.  All Fortran
3799 I/O units are closed. 
3800
3801 @item @emph{Standard}:
3802 GNU extension
3803
3804 @item @emph{Class}:
3805 Subroutine
3806
3807 @item @emph{Syntax}:
3808 @code{CALL EXIT([STATUS])}
3809
3810 @item @emph{Arguments}:
3811 @multitable @columnfractions .15 .70
3812 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3813 @end multitable
3814
3815 @item @emph{Return value}:
3816 @code{STATUS} is passed to the parent process on exit.
3817
3818 @item @emph{Example}:
3819 @smallexample
3820 program test_exit
3821   integer :: STATUS = 0
3822   print *, 'This program is going to exit.'
3823   call EXIT(STATUS)
3824 end program test_exit
3825 @end smallexample
3826
3827 @item @emph{See also}:
3828 @ref{ABORT}, @ref{KILL}
3829 @end table
3830
3831
3832
3833 @node EXP
3834 @section @code{EXP} --- Exponential function 
3835 @fnindex EXP
3836 @fnindex DEXP
3837 @fnindex CEXP
3838 @fnindex ZEXP
3839 @fnindex CDEXP
3840 @cindex exponential function
3841 @cindex logarithmic function, inverse
3842
3843 @table @asis
3844 @item @emph{Description}:
3845 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3846
3847 @item @emph{Standard}:
3848 Fortran 77 and later, has overloads that are GNU extensions
3849
3850 @item @emph{Class}:
3851 Elemental function
3852
3853 @item @emph{Syntax}:
3854 @code{RESULT = EXP(X)}
3855
3856 @item @emph{Arguments}:
3857 @multitable @columnfractions .15 .70
3858 @item @var{X} @tab The type shall be @code{REAL} or
3859 @code{COMPLEX}.
3860 @end multitable
3861
3862 @item @emph{Return value}:
3863 The return value has same type and kind as @var{X}.
3864
3865 @item @emph{Example}:
3866 @smallexample
3867 program test_exp
3868   real :: x = 1.0
3869   x = exp(x)
3870 end program test_exp
3871 @end smallexample
3872
3873 @item @emph{Specific names}:
3874 @multitable @columnfractions .20 .20 .20 .25
3875 @item Name            @tab Argument             @tab Return type         @tab Standard
3876 @item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
3877 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
3878 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3879 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3880 @end multitable
3881 @end table
3882
3883
3884
3885 @node EXPONENT
3886 @section @code{EXPONENT} --- Exponent function 
3887 @fnindex EXPONENT
3888 @cindex real number, exponent
3889 @cindex floating point, exponent
3890
3891 @table @asis
3892 @item @emph{Description}:
3893 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3894 is zero the value returned is zero. 
3895
3896 @item @emph{Standard}:
3897 Fortran 95 and later
3898
3899 @item @emph{Class}:
3900 Elemental function
3901
3902 @item @emph{Syntax}:
3903 @code{RESULT = EXPONENT(X)}
3904
3905 @item @emph{Arguments}:
3906 @multitable @columnfractions .15 .70
3907 @item @var{X} @tab The type shall be @code{REAL}.
3908 @end multitable
3909
3910 @item @emph{Return value}:
3911 The return value is of type default @code{INTEGER}.
3912
3913 @item @emph{Example}:
3914 @smallexample
3915 program test_exponent
3916   real :: x = 1.0
3917   integer :: i
3918   i = exponent(x)
3919   print *, i
3920   print *, exponent(0.0)
3921 end program test_exponent
3922 @end smallexample
3923 @end table
3924
3925
3926
3927 @node FDATE
3928 @section @code{FDATE} --- Get the current time as a string
3929 @fnindex FDATE
3930 @cindex time, current
3931 @cindex current time
3932 @cindex date, current
3933 @cindex current date
3934
3935 @table @asis
3936 @item @emph{Description}:
3937 @code{FDATE(DATE)} returns the current date (using the same format as
3938 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3939 TIME())}.
3940
3941 This intrinsic is provided in both subroutine and function forms; however,
3942 only one form can be used in any given program unit.
3943
3944 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3945 default kind.
3946
3947 @item @emph{Standard}:
3948 GNU extension
3949
3950 @item @emph{Class}:
3951 Subroutine, function
3952
3953 @item @emph{Syntax}:
3954 @multitable @columnfractions .80
3955 @item @code{CALL FDATE(DATE)}.
3956 @item @code{DATE = FDATE()}, (not recommended).
3957 @end multitable
3958
3959 @item @emph{Arguments}:
3960 @multitable @columnfractions .15 .70
3961 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
3962 default kind
3963 @end multitable
3964
3965 @item @emph{Return value}:
3966 The current date as a string.
3967
3968 @item @emph{Example}:
3969 @smallexample
3970 program test_fdate
3971     integer(8) :: i, j
3972     character(len=30) :: date
3973     call fdate(date)
3974     print *, 'Program started on ', date
3975     do i = 1, 100000000 ! Just a delay
3976         j = i * i - i
3977     end do
3978     call fdate(date)
3979     print *, 'Program ended on ', date
3980 end program test_fdate
3981 @end smallexample
3982 @end table
3983
3984
3985
3986 @node FLOAT
3987 @section @code{FLOAT} --- Convert integer to default real
3988 @fnindex FLOAT
3989 @cindex conversion, to real
3990
3991 @table @asis
3992 @item @emph{Description}:
3993 @code{FLOAT(A)} converts the integer @var{A} to a default real value.
3994
3995 @item @emph{Standard}:
3996 Fortran 77 and later
3997
3998 @item @emph{Class}:
3999 Elemental function
4000
4001 @item @emph{Syntax}:
4002 @code{RESULT = FLOAT(A)}
4003
4004 @item @emph{Arguments}:
4005 @multitable @columnfractions .15 .70
4006 @item @var{A} @tab The type shall be @code{INTEGER}.
4007 @end multitable
4008
4009 @item @emph{Return value}:
4010 The return value is of type default @code{REAL}.
4011
4012 @item @emph{Example}:
4013 @smallexample
4014 program test_float
4015     integer :: i = 1
4016     if (float(i) /= 1.) call abort
4017 end program test_float
4018 @end smallexample
4019
4020 @item @emph{See also}:
4021 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
4022 @end table
4023
4024
4025
4026 @node FGET
4027 @section @code{FGET} --- Read a single character in stream mode from stdin 
4028 @fnindex FGET
4029 @cindex read character, stream mode
4030 @cindex stream mode, read character
4031 @cindex file operation, read character
4032
4033 @table @asis
4034 @item @emph{Description}:
4035 Read a single character in stream mode from stdin by bypassing normal 
4036 formatted output. Stream I/O should not be mixed with normal record-oriented 
4037 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4038
4039 This intrinsic is provided in both subroutine and function forms; however,
4040 only one form can be used in any given program unit.
4041
4042 Note that the @code{FGET} intrinsic is provided for backwards compatibility with 
4043 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4044 Programmers should consider the use of new stream IO feature in new code 
4045 for future portability. See also @ref{Fortran 2003 status}.
4046
4047 @item @emph{Standard}:
4048 GNU extension
4049
4050 @item @emph{Class}:
4051 Subroutine, function
4052
4053 @item @emph{Syntax}:
4054 @code{CALL FGET(C [, STATUS])}
4055
4056 @item @emph{Arguments}:
4057 @multitable @columnfractions .15 .70
4058 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4059 kind.
4060 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4061 Returns 0 on success, -1 on end-of-file, and a system specific positive
4062 error code otherwise.
4063 @end multitable
4064
4065 @item @emph{Example}:
4066 @smallexample
4067 PROGRAM test_fget
4068   INTEGER, PARAMETER :: strlen = 100
4069   INTEGER :: status, i = 1
4070   CHARACTER(len=strlen) :: str = ""
4071
4072   WRITE (*,*) 'Enter text:'
4073   DO
4074     CALL fget(str(i:i), status)
4075     if (status /= 0 .OR. i > strlen) exit
4076     i = i + 1
4077   END DO
4078   WRITE (*,*) TRIM(str)
4079 END PROGRAM
4080 @end smallexample
4081
4082 @item @emph{See also}:
4083 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4084 @end table
4085
4086
4087
4088 @node FGETC
4089 @section @code{FGETC} --- Read a single character in stream mode
4090 @fnindex FGETC
4091 @cindex read character, stream mode
4092 @cindex stream mode, read character
4093 @cindex file operation, read character
4094
4095 @table @asis
4096 @item @emph{Description}:
4097 Read a single character in stream mode by bypassing normal formatted output. 
4098 Stream I/O should not be mixed with normal record-oriented (formatted or 
4099 unformatted) I/O on the same unit; the results are unpredictable.
4100
4101 This intrinsic is provided in both subroutine and function forms; however,
4102 only one form can be used in any given program unit.
4103
4104 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4105 with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4106 Programmers should consider the use of new stream IO feature in new code 
4107 for future portability. See also @ref{Fortran 2003 status}.
4108
4109 @item @emph{Standard}:
4110 GNU extension
4111
4112 @item @emph{Class}:
4113 Subroutine, function
4114
4115 @item @emph{Syntax}:
4116 @code{CALL FGETC(UNIT, C [, STATUS])}
4117
4118 @item @emph{Arguments}:
4119 @multitable @columnfractions .15 .70
4120 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4121 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4122 kind.
4123 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4124 Returns 0 on success, -1 on end-of-file and a system specific positive
4125 error code otherwise.
4126 @end multitable
4127
4128 @item @emph{Example}:
4129 @smallexample
4130 PROGRAM test_fgetc
4131   INTEGER :: fd = 42, status
4132   CHARACTER :: c
4133
4134   OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4135   DO
4136     CALL fgetc(fd, c, status)
4137     IF (status /= 0) EXIT
4138     call fput(c)
4139   END DO
4140   CLOSE(UNIT=fd)
4141 END PROGRAM
4142 @end smallexample
4143
4144 @item @emph{See also}:
4145 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4146 @end table
4147
4148
4149
4150 @node FLOOR
4151 @section @code{FLOOR} --- Integer floor function
4152 @fnindex FLOOR
4153 @cindex floor
4154 @cindex rounding, floor
4155
4156 @table @asis
4157 @item @emph{Description}:
4158 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4159
4160 @item @emph{Standard}:
4161 Fortran 95 and later
4162
4163 @item @emph{Class}:
4164 Elemental function
4165
4166 @item @emph{Syntax}:
4167 @code{RESULT = FLOOR(A [, KIND])}
4168
4169 @item @emph{Arguments}:
4170 @multitable @columnfractions .15 .70
4171 @item @var{A} @tab The type shall be @code{REAL}.
4172 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4173 expression indicating the kind parameter of the result.
4174 @end multitable
4175
4176 @item @emph{Return value}:
4177 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4178 and of default-kind @code{INTEGER} otherwise.
4179
4180 @item @emph{Example}:
4181 @smallexample
4182 program test_floor
4183     real :: x = 63.29
4184     real :: y = -63.59
4185     print *, floor(x) ! returns 63
4186     print *, floor(y) ! returns -64
4187 end program test_floor
4188 @end smallexample
4189
4190 @item @emph{See also}:
4191 @ref{CEILING}, @ref{NINT}
4192
4193 @end table
4194
4195
4196
4197 @node FLUSH
4198 @section @code{FLUSH} --- Flush I/O unit(s)
4199 @fnindex FLUSH
4200 @cindex file operation, flush
4201
4202 @table @asis
4203 @item @emph{Description}:
4204 Flushes Fortran unit(s) currently open for output. Without the optional
4205 argument, all units are flushed, otherwise just the unit specified.
4206
4207 @item @emph{Standard}:
4208 GNU extension
4209
4210 @item @emph{Class}:
4211 Subroutine
4212
4213 @item @emph{Syntax}:
4214 @code{CALL FLUSH(UNIT)}
4215
4216 @item @emph{Arguments}:
4217 @multitable @columnfractions .15 .70
4218 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4219 @end multitable
4220
4221 @item @emph{Note}:
4222 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4223 statement that should be preferred over the @code{FLUSH} intrinsic.
4224
4225 @end table
4226
4227
4228
4229 @node FNUM
4230 @section @code{FNUM} --- File number function
4231 @fnindex FNUM
4232 @cindex file operation, file number
4233
4234 @table @asis
4235 @item @emph{Description}:
4236 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4237 open Fortran I/O unit @code{UNIT}.
4238
4239 @item @emph{Standard}:
4240 GNU extension
4241
4242 @item @emph{Class}:
4243 Function
4244
4245 @item @emph{Syntax}:
4246 @code{RESULT = FNUM(UNIT)}
4247
4248 @item @emph{Arguments}:
4249 @multitable @columnfractions .15 .70
4250 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4251 @end multitable
4252
4253 @item @emph{Return value}:
4254 The return value is of type @code{INTEGER}
4255
4256 @item @emph{Example}:
4257 @smallexample
4258 program test_fnum
4259   integer :: i
4260   open (unit=10, status = "scratch")
4261   i = fnum(10)
4262   print *, i
4263   close (10)
4264 end program test_fnum
4265 @end smallexample
4266 @end table
4267
4268
4269
4270 @node FPUT
4271 @section @code{FPUT} --- Write a single character in stream mode to stdout 
4272 @fnindex FPUT
4273 @cindex write character, stream mode
4274 @cindex stream mode, write character
4275 @cindex file operation, write character
4276
4277 @table @asis
4278 @item @emph{Description}:
4279 Write a single character in stream mode to stdout by bypassing normal 
4280 formatted output. Stream I/O should not be mixed with normal record-oriented 
4281 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4282
4283 This intrinsic is provided in both subroutine and function forms; however,
4284 only one form can be used in any given program unit.
4285
4286 Note that the @code{FGET} intrinsic is provided for backwards compatibility with 
4287 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4288 Programmers should consider the use of new stream IO feature in new code 
4289 for future portability. See also @ref{Fortran 2003 status}.
4290
4291 @item @emph{Standard}:
4292 GNU extension
4293
4294 @item @emph{Class}:
4295 Subroutine, function
4296
4297 @item @emph{Syntax}:
4298 @code{CALL FPUT(C [, STATUS])}
4299
4300 @item @emph{Arguments}:
4301 @multitable @columnfractions .15 .70
4302 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4303 kind.
4304 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4305 Returns 0 on success, -1 on end-of-file and a system specific positive
4306 error code otherwise.
4307 @end multitable
4308
4309 @item @emph{Example}:
4310 @smallexample
4311 PROGRAM test_fput
4312   CHARACTER(len=10) :: str = "gfortran"
4313   INTEGER :: i
4314   DO i = 1, len_trim(str)
4315     CALL fput(str(i:i))
4316   END DO
4317 END PROGRAM
4318 @end smallexample
4319
4320 @item @emph{See also}:
4321 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4322 @end table
4323
4324
4325
4326 @node FPUTC
4327 @section @code{FPUTC} --- Write a single character in stream mode
4328 @fnindex FPUTC
4329 @cindex write character, stream mode
4330 @cindex stream mode, write character
4331 @cindex file operation, write character
4332
4333 @table @asis
4334 @item @emph{Description}:
4335 Write a single character in stream mode by bypassing normal formatted 
4336 output. Stream I/O should not be mixed with normal record-oriented 
4337 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4338
4339 This intrinsic is provided in both subroutine and function forms; however,
4340 only one form can be used in any given program unit.
4341
4342 Note that the @code{FGET} intrinsic is provided for backwards compatibility with 
4343 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4344 Programmers should consider the use of new stream IO feature in new code 
4345 for future portability. See also @ref{Fortran 2003 status}.
4346
4347 @item @emph{Standard}:
4348 GNU extension
4349
4350 @item @emph{Class}:
4351 Subroutine, function
4352
4353 @item @emph{Syntax}:
4354 @code{CALL FPUTC(UNIT, C [, STATUS])}
4355
4356 @item @emph{Arguments}:
4357 @multitable @columnfractions .15 .70
4358 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4359 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4360 kind.
4361 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4362 Returns 0 on success, -1 on end-of-file and a system specific positive
4363 error code otherwise.
4364 @end multitable
4365
4366 @item @emph{Example}:
4367 @smallexample
4368 PROGRAM test_fputc
4369   CHARACTER(len=10) :: str = "gfortran"
4370   INTEGER :: fd = 42, i
4371
4372   OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4373   DO i = 1, len_trim(str)
4374     CALL fputc(fd, str(i:i))
4375   END DO
4376   CLOSE(fd)
4377 END PROGRAM
4378 @end smallexample
4379
4380 @item @emph{See also}:
4381 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4382 @end table
4383
4384
4385
4386 @node FRACTION
4387 @section @code{FRACTION} --- Fractional part of the model representation
4388 @fnindex FRACTION
4389 @cindex real number, fraction
4390 @cindex floating point, fraction
4391
4392 @table @asis
4393 @item @emph{Description}:
4394 @code{FRACTION(X)} returns the fractional part of the model
4395 representation of @code{X}.
4396
4397 @item @emph{Standard}:
4398 Fortran 95 and later
4399
4400 @item @emph{Class}:
4401 Elemental function
4402
4403 @item @emph{Syntax}:
4404 @code{Y = FRACTION(X)}
4405
4406 @item @emph{Arguments}:
4407 @multitable @columnfractions .15 .70
4408 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4409 @end multitable
4410
4411 @item @emph{Return value}:
4412 The return value is of the same type and kind as the argument.
4413 The fractional part of the model representation of @code{X} is returned;
4414 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4415
4416 @item @emph{Example}:
4417 @smallexample
4418 program test_fraction
4419   real :: x
4420   x = 178.1387e-4
4421   print *, fraction(x), x * radix(x)**(-exponent(x))
4422 end program test_fraction
4423 @end smallexample
4424
4425 @end table
4426
4427
4428
4429 @node FREE
4430 @section @code{FREE} --- Frees memory
4431 @fnindex FREE
4432 @cindex pointer, cray
4433
4434 @table @asis
4435 @item @emph{Description}:
4436 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4437 intrinsic is an extension intended to be used with Cray pointers, and is
4438 provided in GNU Fortran to allow user to compile legacy code. For
4439 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4440 @code{DEALLOCATE}.
4441
4442 @item @emph{Standard}:
4443 GNU extension
4444
4445 @item @emph{Class}:
4446 Subroutine