OSDN Git Service

2009-01-04 Tobias Burnus <burnus@net-b.de>
[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, for a complex argument Fortran 2008 or 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 either be @code{REAL} with a magnitude that is
545 less than or equal to one - or the type shall be @code{COMPLEX}.
546 @end multitable
547
548 @item @emph{Return value}:
549 The return value is of the same type and kind as @var{X}.
550 The real part of the result is in radians and lies in the range
551 @math{0 \leq \Re \acos(x) \leq \pi}.
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}. If @var{X} is
604 complex, the imaginary part of the result is in radians and lies between
605 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
606
607 @item @emph{Example}:
608 @smallexample
609 PROGRAM test_acosh
610   REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
611   WRITE (*,*) ACOSH(x)
612 END PROGRAM
613 @end smallexample
614
615 @item @emph{Specific names}:
616 @multitable @columnfractions .20 .20 .20 .25
617 @item Name             @tab Argument          @tab Return type       @tab Standard
618 @item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
619 @end multitable
620
621 @item @emph{See also}:
622 Inverse function: @ref{COSH}
623 @end table
624
625
626
627 @node ADJUSTL
628 @section @code{ADJUSTL} --- Left adjust a string 
629 @fnindex ADJUSTL
630 @cindex string, adjust left
631 @cindex adjust string
632
633 @table @asis
634 @item @emph{Description}:
635 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
636 Spaces are inserted at the end of the string as needed.
637
638 @item @emph{Standard}:
639 Fortran 90 and later
640
641 @item @emph{Class}:
642 Elemental function
643
644 @item @emph{Syntax}:
645 @code{RESULT = ADJUSTL(STRING)}
646
647 @item @emph{Arguments}:
648 @multitable @columnfractions .15 .70
649 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
650 @end multitable
651
652 @item @emph{Return value}:
653 The return value is of type @code{CHARACTER} and of the same kind as
654 @var{STRING} where leading spaces are removed and the same number of
655 spaces are inserted on the end of @var{STRING}.
656
657 @item @emph{Example}:
658 @smallexample
659 program test_adjustl
660   character(len=20) :: str = '   gfortran'
661   str = adjustl(str)
662   print *, str
663 end program test_adjustl
664 @end smallexample
665
666 @item @emph{See also}:
667 @ref{ADJUSTR}, @ref{TRIM}
668 @end table
669
670
671
672 @node ADJUSTR
673 @section @code{ADJUSTR} --- Right adjust a string 
674 @fnindex ADJUSTR
675 @cindex string, adjust right
676 @cindex adjust string
677
678 @table @asis
679 @item @emph{Description}:
680 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
681 Spaces are inserted at the start of the string as needed.
682
683 @item @emph{Standard}:
684 Fortran 95 and later
685
686 @item @emph{Class}:
687 Elemental function
688
689 @item @emph{Syntax}:
690 @code{RESULT = ADJUSTR(STRING)}
691
692 @item @emph{Arguments}:
693 @multitable @columnfractions .15 .70
694 @item @var{STR} @tab The type shall be @code{CHARACTER}.
695 @end multitable
696
697 @item @emph{Return value}:
698 The return value is of type @code{CHARACTER} and of the same kind as
699 @var{STRING} where trailing spaces are removed and the same number of
700 spaces are inserted at the start of @var{STRING}.
701
702 @item @emph{Example}:
703 @smallexample
704 program test_adjustr
705   character(len=20) :: str = 'gfortran'
706   str = adjustr(str)
707   print *, str
708 end program test_adjustr
709 @end smallexample
710
711 @item @emph{See also}:
712 @ref{ADJUSTL}, @ref{TRIM}
713 @end table
714
715
716
717 @node AIMAG
718 @section @code{AIMAG} --- Imaginary part of complex number  
719 @fnindex AIMAG
720 @fnindex DIMAG
721 @fnindex IMAG
722 @fnindex IMAGPART
723 @cindex complex numbers, imaginary part
724
725 @table @asis
726 @item @emph{Description}:
727 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
728 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
729 for compatibility with @command{g77}, and their use in new code is 
730 strongly discouraged.
731
732 @item @emph{Standard}:
733 Fortran 77 and later, has overloads that are GNU extensions
734
735 @item @emph{Class}:
736 Elemental function
737
738 @item @emph{Syntax}:
739 @code{RESULT = AIMAG(Z)}
740
741 @item @emph{Arguments}:
742 @multitable @columnfractions .15 .70
743 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
744 @end multitable
745
746 @item @emph{Return value}:
747 The return value is of type @code{REAL} with the
748 kind type parameter of the argument.
749
750 @item @emph{Example}:
751 @smallexample
752 program test_aimag
753   complex(4) z4
754   complex(8) z8
755   z4 = cmplx(1.e0_4, 0.e0_4)
756   z8 = cmplx(0.e0_8, 1.e0_8)
757   print *, aimag(z4), dimag(z8)
758 end program test_aimag
759 @end smallexample
760
761 @item @emph{Specific names}:
762 @multitable @columnfractions .20 .20 .20 .25
763 @item Name            @tab Argument            @tab Return type       @tab Standard
764 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}    @tab GNU extension
765 @item @code{IMAG(Z)}  @tab @code{COMPLEX Z} @tab @code{REAL}    @tab GNU extension
766 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
767 @end multitable
768 @end table
769
770
771
772 @node AINT
773 @section @code{AINT} --- Truncate to a whole number
774 @fnindex AINT
775 @fnindex DINT
776 @cindex floor
777 @cindex rounding, floor
778
779 @table @asis
780 @item @emph{Description}:
781 @code{AINT(A [, KIND])} truncates its argument to a whole number.
782
783 @item @emph{Standard}:
784 Fortran 77 and later
785
786 @item @emph{Class}:
787 Elemental function
788
789 @item @emph{Syntax}:
790 @code{RESULT = AINT(A [, KIND])} 
791
792 @item @emph{Arguments}:
793 @multitable @columnfractions .15 .70
794 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
795 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
796 expression indicating the kind parameter of the result.
797 @end multitable
798
799 @item @emph{Return value}:
800 The return value is of type @code{REAL} with the kind type parameter of the
801 argument if the optional @var{KIND} is absent; otherwise, the kind
802 type parameter will be given by @var{KIND}.  If the magnitude of 
803 @var{X} is less than one, @code{AINT(X)} returns zero.  If the
804 magnitude is equal to or greater than one then it returns the largest
805 whole number that does not exceed its magnitude.  The sign is the same
806 as the sign of @var{X}. 
807
808 @item @emph{Example}:
809 @smallexample
810 program test_aint
811   real(4) x4
812   real(8) x8
813   x4 = 1.234E0_4
814   x8 = 4.321_8
815   print *, aint(x4), dint(x8)
816   x8 = aint(x4,8)
817 end program test_aint
818 @end smallexample
819
820 @item @emph{Specific names}:
821 @multitable @columnfractions .20 .20 .20 .25
822 @item Name           @tab Argument         @tab Return type      @tab Standard
823 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab Fortran 77 and later
824 @end multitable
825 @end table
826
827
828
829 @node ALARM
830 @section @code{ALARM} --- Execute a routine after a given delay
831 @fnindex ALARM
832 @cindex delayed execution
833
834 @table @asis
835 @item @emph{Description}:
836 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
837 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
838 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
839 supplied, it will be returned with the number of seconds remaining until
840 any previously scheduled alarm was due to be delivered, or zero if there
841 was no previously scheduled alarm.
842
843 @item @emph{Standard}:
844 GNU extension
845
846 @item @emph{Class}:
847 Subroutine
848
849 @item @emph{Syntax}:
850 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
851
852 @item @emph{Arguments}:
853 @multitable @columnfractions .15 .70
854 @item @var{SECONDS} @tab The type of the argument shall be a scalar
855 @code{INTEGER}. It is @code{INTENT(IN)}.
856 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
857 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 
858 values may be either @code{SIG_IGN=1} to ignore the alarm generated 
859 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
860 @item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
861 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
862 @end multitable
863
864 @item @emph{Example}:
865 @smallexample
866 program test_alarm
867   external handler_print
868   integer i
869   call alarm (3, handler_print, i)
870   print *, i
871   call sleep(10)
872 end program test_alarm
873 @end smallexample
874 This will cause the external routine @var{handler_print} to be called
875 after 3 seconds.
876 @end table
877
878
879
880 @node ALL
881 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 
882 @fnindex ALL
883 @cindex array, apply condition
884 @cindex array, condition testing
885
886 @table @asis
887 @item @emph{Description}:
888 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
889 in the array along dimension @var{DIM}.
890
891 @item @emph{Standard}:
892 Fortran 95 and later
893
894 @item @emph{Class}:
895 Transformational function
896
897 @item @emph{Syntax}:
898 @code{RESULT = ALL(MASK [, DIM])}
899
900 @item @emph{Arguments}:
901 @multitable @columnfractions .15 .70
902 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
903 it shall not be scalar.
904 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
905 with a value that lies between one and the rank of @var{MASK}.
906 @end multitable
907
908 @item @emph{Return value}:
909 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
910 the kind type parameter is the same as the kind type parameter of
911 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
912 an array with the rank of @var{MASK} minus 1.  The shape is determined from
913 the shape of @var{MASK} where the @var{DIM} dimension is elided. 
914
915 @table @asis
916 @item (A)
917 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
918 It also is true if @var{MASK} has zero size; otherwise, it is false.
919 @item (B)
920 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
921 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
922 is determined by applying @code{ALL} to the array sections.
923 @end table
924
925 @item @emph{Example}:
926 @smallexample
927 program test_all
928   logical l
929   l = all((/.true., .true., .true./))
930   print *, l
931   call section
932   contains
933     subroutine section
934       integer a(2,3), b(2,3)
935       a = 1
936       b = 1
937       b(2,2) = 2
938       print *, all(a .eq. b, 1)
939       print *, all(a .eq. b, 2)
940     end subroutine section
941 end program test_all
942 @end smallexample
943 @end table
944
945
946
947 @node ALLOCATED
948 @section @code{ALLOCATED} --- Status of an allocatable entity
949 @fnindex ALLOCATED
950 @cindex allocation, status
951
952 @table @asis
953 @item @emph{Description}:
954 @code{ALLOCATED(ARRAY)} checks the status of whether @var{X} is allocated.
955
956 @item @emph{Standard}:
957 Fortran 95 and later
958
959 @item @emph{Class}:
960 Inquiry function
961
962 @item @emph{Syntax}:
963 @code{RESULT = ALLOCATED(ARRAY)}
964
965 @item @emph{Arguments}:
966 @multitable @columnfractions .15 .70
967 @item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
968 @end multitable
969
970 @item @emph{Return value}:
971 The return value is a scalar @code{LOGICAL} with the default logical
972 kind type parameter.  If @var{ARRAY} is allocated, @code{ALLOCATED(ARRAY)}
973 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.} 
974
975 @item @emph{Example}:
976 @smallexample
977 program test_allocated
978   integer :: i = 4
979   real(4), allocatable :: x(:)
980   if (.not. allocated(x)) allocate(x(i))
981 end program test_allocated
982 @end smallexample
983 @end table
984
985
986
987 @node AND
988 @section @code{AND} --- Bitwise logical AND
989 @fnindex AND
990 @cindex bitwise logical and
991 @cindex logical and, bitwise
992
993 @table @asis
994 @item @emph{Description}:
995 Bitwise logical @code{AND}.
996
997 This intrinsic routine is provided for backwards compatibility with 
998 GNU Fortran 77.  For integer arguments, programmers should consider
999 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1000
1001 @item @emph{Standard}:
1002 GNU extension
1003
1004 @item @emph{Class}:
1005 Function
1006
1007 @item @emph{Syntax}:
1008 @code{RESULT = AND(I, J)}
1009
1010 @item @emph{Arguments}:
1011 @multitable @columnfractions .15 .70
1012 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1013 type or a scalar @code{LOGICAL} type.
1014 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1015 @end multitable
1016
1017 @item @emph{Return value}:
1018 The return type is either a scalar @code{INTEGER} or a scalar
1019 @code{LOGICAL}.  If the kind type parameters differ, then the
1020 smaller kind type is implicitly converted to larger kind, and the 
1021 return has the larger kind.
1022
1023 @item @emph{Example}:
1024 @smallexample
1025 PROGRAM test_and
1026   LOGICAL :: T = .TRUE., F = .FALSE.
1027   INTEGER :: a, b
1028   DATA a / Z'F' /, b / Z'3' /
1029
1030   WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1031   WRITE (*,*) AND(a, b)
1032 END PROGRAM
1033 @end smallexample
1034
1035 @item @emph{See also}:
1036 Fortran 95 elemental function: @ref{IAND}
1037 @end table
1038
1039
1040
1041 @node ANINT
1042 @section @code{ANINT} --- Nearest whole number
1043 @fnindex ANINT
1044 @fnindex DNINT
1045 @cindex ceiling
1046 @cindex rounding, ceiling
1047
1048 @table @asis
1049 @item @emph{Description}:
1050 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1051
1052 @item @emph{Standard}:
1053 Fortran 77 and later
1054
1055 @item @emph{Class}:
1056 Elemental function
1057
1058 @item @emph{Syntax}:
1059 @code{RESULT = ANINT(A [, KIND])}
1060
1061 @item @emph{Arguments}:
1062 @multitable @columnfractions .15 .70
1063 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
1064 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1065 expression indicating the kind parameter of the result.
1066 @end multitable
1067
1068 @item @emph{Return value}:
1069 The return value is of type real with the kind type parameter of the
1070 argument if the optional @var{KIND} is absent; otherwise, the kind
1071 type parameter will be given by @var{KIND}.  If @var{A} is greater than
1072 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
1073 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1074
1075 @item @emph{Example}:
1076 @smallexample
1077 program test_anint
1078   real(4) x4
1079   real(8) x8
1080   x4 = 1.234E0_4
1081   x8 = 4.321_8
1082   print *, anint(x4), dnint(x8)
1083   x8 = anint(x4,8)
1084 end program test_anint
1085 @end smallexample
1086
1087 @item @emph{Specific names}:
1088 @multitable @columnfractions .20 .20 .20 .25
1089 @item Name            @tab Argument         @tab Return type      @tab Standard
1090 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
1091 @end multitable
1092 @end table
1093
1094
1095
1096 @node ANY
1097 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 
1098 @fnindex ANY
1099 @cindex array, apply condition
1100 @cindex array, condition testing
1101
1102 @table @asis
1103 @item @emph{Description}:
1104 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1105 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1106
1107 @item @emph{Standard}:
1108 Fortran 95 and later
1109
1110 @item @emph{Class}:
1111 Transformational function
1112
1113 @item @emph{Syntax}:
1114 @code{RESULT = ANY(MASK [, DIM])}
1115
1116 @item @emph{Arguments}:
1117 @multitable @columnfractions .15 .70
1118 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1119 it shall not be scalar.
1120 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1121 with a value that lies between one and the rank of @var{MASK}.
1122 @end multitable
1123
1124 @item @emph{Return value}:
1125 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1126 the kind type parameter is the same as the kind type parameter of
1127 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1128 an array with the rank of @var{MASK} minus 1.  The shape is determined from
1129 the shape of @var{MASK} where the @var{DIM} dimension is elided. 
1130
1131 @table @asis
1132 @item (A)
1133 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1134 otherwise, it is false.  It also is false if @var{MASK} has zero size.
1135 @item (B)
1136 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1137 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1138 is determined by applying @code{ANY} to the array sections.
1139 @end table
1140
1141 @item @emph{Example}:
1142 @smallexample
1143 program test_any
1144   logical l
1145   l = any((/.true., .true., .true./))
1146   print *, l
1147   call section
1148   contains
1149     subroutine section
1150       integer a(2,3), b(2,3)
1151       a = 1
1152       b = 1
1153       b(2,2) = 2
1154       print *, any(a .eq. b, 1)
1155       print *, any(a .eq. b, 2)
1156     end subroutine section
1157 end program test_any
1158 @end smallexample
1159 @end table
1160
1161
1162
1163 @node ASIN
1164 @section @code{ASIN} --- Arcsine function 
1165 @fnindex ASIN
1166 @fnindex DASIN
1167 @cindex trigonometric function, sine, inverse
1168 @cindex sine, inverse
1169
1170 @table @asis
1171 @item @emph{Description}:
1172 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1173
1174 @item @emph{Standard}:
1175 Fortran 77 and later, for a complex argument Fortran 2008 or later
1176
1177 @item @emph{Class}:
1178 Elemental function
1179
1180 @item @emph{Syntax}:
1181 @code{RESULT = ASIN(X)}
1182
1183 @item @emph{Arguments}:
1184 @multitable @columnfractions .15 .70
1185 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1186 less than or equal to one - or be @code{COMPLEX}.
1187 @end multitable
1188
1189 @item @emph{Return value}:
1190 The return value is of the same type and kind as @var{X}.
1191 The real part of the result is in radians and lies in the range
1192 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1193
1194 @item @emph{Example}:
1195 @smallexample
1196 program test_asin
1197   real(8) :: x = 0.866_8
1198   x = asin(x)
1199 end program test_asin
1200 @end smallexample
1201
1202 @item @emph{Specific names}:
1203 @multitable @columnfractions .20 .20 .20 .25
1204 @item Name            @tab Argument          @tab Return type       @tab Standard
1205 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1206 @end multitable
1207
1208 @item @emph{See also}:
1209 Inverse function: @ref{SIN}
1210
1211 @end table
1212
1213
1214
1215 @node ASINH
1216 @section @code{ASINH} --- Hyperbolic arcsine function
1217 @fnindex ASINH
1218 @fnindex DASINH
1219 @cindex area hyperbolic sine
1220 @cindex hyperbolic arcsine
1221 @cindex hyperbolic function, sine, inverse
1222 @cindex sine, hyperbolic, inverse
1223
1224 @table @asis
1225 @item @emph{Description}:
1226 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1227
1228 @item @emph{Standard}:
1229 Fortran 2008 and later
1230
1231 @item @emph{Class}:
1232 Elemental function
1233
1234 @item @emph{Syntax}:
1235 @code{RESULT = ASINH(X)}
1236
1237 @item @emph{Arguments}:
1238 @multitable @columnfractions .15 .70
1239 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1240 @end multitable
1241
1242 @item @emph{Return value}:
1243 The return value is of the same type and kind as  @var{X}. If @var{X} is
1244 complex, the imaginary part of the result is in radians and lies between
1245 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1246
1247 @item @emph{Example}:
1248 @smallexample
1249 PROGRAM test_asinh
1250   REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1251   WRITE (*,*) ASINH(x)
1252 END PROGRAM
1253 @end smallexample
1254
1255 @item @emph{Specific names}:
1256 @multitable @columnfractions .20 .20 .20 .25
1257 @item Name             @tab Argument          @tab Return type       @tab Standard
1258 @item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1259 @end multitable
1260
1261 @item @emph{See also}:
1262 Inverse function: @ref{SINH}
1263 @end table
1264
1265
1266
1267 @node ASSOCIATED
1268 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 
1269 @fnindex ASSOCIATED
1270 @cindex pointer, status
1271 @cindex association status
1272
1273 @table @asis
1274 @item @emph{Description}:
1275 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1276 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1277
1278 @item @emph{Standard}:
1279 Fortran 95 and later
1280
1281 @item @emph{Class}:
1282 Inquiry function
1283
1284 @item @emph{Syntax}:
1285 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1286
1287 @item @emph{Arguments}:
1288 @multitable @columnfractions .15 .70
1289 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1290 and it can be of any type.
1291 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1292 a target.  It must have the same type, kind type parameter, and
1293 array rank as @var{POINTER}.
1294 @end multitable
1295 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1296 undefined.
1297
1298 @item @emph{Return value}:
1299 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1300 There are several cases:
1301 @table @asis
1302 @item (A) When the optional @var{TARGET} is not present then
1303 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1304 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1305 @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
1306 disassociated, the result is false.
1307 @item (C) If @var{TARGET} is present and an array target, the result is true if
1308 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1309 are arrays whose elements are not zero-sized storage sequences, and
1310 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1311 order.
1312 As in case(B), the result is false, if @var{POINTER} is disassociated.
1313 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1314 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1315 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1316 units.
1317 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1318 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1319 target associated with @var{POINTER} and the target associated with @var{TARGET}
1320 have the same shape, are not zero-sized arrays, are arrays whose elements are
1321 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1322 the same storage units in array element order.
1323 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1324 @end table
1325
1326 @item @emph{Example}:
1327 @smallexample
1328 program test_associated
1329    implicit none
1330    real, target  :: tgt(2) = (/1., 2./)
1331    real, pointer :: ptr(:)
1332    ptr => tgt
1333    if (associated(ptr)     .eqv. .false.) call abort
1334    if (associated(ptr,tgt) .eqv. .false.) call abort
1335 end program test_associated
1336 @end smallexample
1337
1338 @item @emph{See also}:
1339 @ref{NULL}
1340 @end table
1341
1342
1343
1344 @node ATAN
1345 @section @code{ATAN} --- Arctangent function 
1346 @fnindex ATAN
1347 @fnindex DATAN
1348 @cindex trigonometric function, tangent, inverse
1349 @cindex tangent, inverse
1350
1351 @table @asis
1352 @item @emph{Description}:
1353 @code{ATAN(X)} computes the arctangent of @var{X}.
1354
1355 @item @emph{Standard}:
1356 Fortran 77 and later, for a complex argument and for two arguments
1357 Fortran 2008 or later
1358
1359 @item @emph{Class}:
1360 Elemental function
1361
1362 @item @emph{Syntax}:
1363 @code{RESULT = ATAN(X)}
1364 @code{RESULT = ATAN(Y, X)}
1365
1366 @item @emph{Arguments}:
1367 @multitable @columnfractions .15 .70
1368 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1369 if @var{Y} is present, @var{X} shall be REAL.
1370 @item @var{Y} shall be of the same type and kind as @var{X}.
1371 @end multitable
1372
1373 @item @emph{Return value}:
1374 The return value is of the same type and kind as @var{X}.
1375 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1376 Otherwise, it the arcus tangent of @var{X}, where the real part of
1377 the result is in radians and lies in the range
1378 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1379
1380 @item @emph{Example}:
1381 @smallexample
1382 program test_atan
1383   real(8) :: x = 2.866_8
1384   x = atan(x)
1385 end program test_atan
1386 @end smallexample
1387
1388 @item @emph{Specific names}:
1389 @multitable @columnfractions .20 .20 .20 .25
1390 @item Name            @tab Argument          @tab Return type       @tab Standard
1391 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1392 @end multitable
1393
1394 @item @emph{See also}:
1395 Inverse function: @ref{TAN}
1396
1397 @end table
1398
1399
1400
1401 @node ATAN2
1402 @section @code{ATAN2} --- Arctangent function 
1403 @fnindex ATAN2
1404 @fnindex DATAN2
1405 @cindex trigonometric function, tangent, inverse
1406 @cindex tangent, inverse
1407
1408 @table @asis
1409 @item @emph{Description}:
1410 @code{ATAN2(Y, X)} computes the principal value of the argument
1411 function of the complex number @math{X + i Y}. This function can
1412 be used to transform from carthesian into polar coordinates and
1413 allows to determine the angle in the correct quadrant.
1414
1415 @item @emph{Standard}:
1416 Fortran 77 and later
1417
1418 @item @emph{Class}:
1419 Elemental function
1420
1421 @item @emph{Syntax}:
1422 @code{RESULT = ATAN2(Y, X)}
1423
1424 @item @emph{Arguments}:
1425 @multitable @columnfractions .15 .70
1426 @item @var{Y} @tab The type shall be @code{REAL}.
1427 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1428 If @var{Y} is zero, then @var{X} must be nonzero.
1429 @end multitable
1430
1431 @item @emph{Return value}:
1432 The return value has the same type and kind type parameter as @var{Y}.
1433 It is the principal value of the complex number @math{X + i Y}.  If
1434 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1435 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1436 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1437 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
1438 is @math{\pi/2}.
1439
1440 @item @emph{Example}:
1441 @smallexample
1442 program test_atan2
1443   real(4) :: x = 1.e0_4, y = 0.5e0_4
1444   x = atan2(y,x)
1445 end program test_atan2
1446 @end smallexample
1447
1448 @item @emph{Specific names}:
1449 @multitable @columnfractions .20 .20 .20 .25
1450 @item Name            @tab Argument          @tab Return type    @tab Standard
1451 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X}, @code{REAL(8) Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1452 @end multitable
1453 @end table
1454
1455
1456
1457 @node ATANH
1458 @section @code{ATANH} --- Hyperbolic arctangent function
1459 @fnindex ASINH
1460 @fnindex DASINH
1461 @cindex area hyperbolic tangent
1462 @cindex hyperbolic arctangent
1463 @cindex hyperbolic function, tangent, inverse
1464 @cindex tangent, hyperbolic, inverse
1465
1466 @table @asis
1467 @item @emph{Description}:
1468 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1469 of @code{TANH(X)}).
1470
1471 @item @emph{Standard}:
1472 Fortran 2008 and later
1473
1474 @item @emph{Class}:
1475 Elemental function
1476
1477 @item @emph{Syntax}:
1478 @code{RESULT = ATANH(X)}
1479
1480 @item @emph{Arguments}:
1481 @multitable @columnfractions .15 .70
1482 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1483 @end multitable
1484
1485 @item @emph{Return value}:
1486 The return value has same type and kind as @var{X}. If @var{X} is
1487 complex, the imaginary part of the result is in radians and lies between
1488 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1489
1490 @item @emph{Example}:
1491 @smallexample
1492 PROGRAM test_atanh
1493   REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1494   WRITE (*,*) ATANH(x)
1495 END PROGRAM
1496 @end smallexample
1497
1498 @item @emph{Specific names}:
1499 @multitable @columnfractions .20 .20 .20 .25
1500 @item Name             @tab Argument          @tab Return type       @tab Standard
1501 @item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1502 @end multitable
1503
1504 @item @emph{See also}:
1505 Inverse function: @ref{TANH}
1506 @end table
1507
1508
1509
1510 @node BESSEL_J0
1511 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1512 @fnindex BESSEL_J0
1513 @fnindex BESJ0
1514 @fnindex DBESJ0
1515 @cindex Bessel function, first kind
1516
1517 @table @asis
1518 @item @emph{Description}:
1519 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1520 order 0 of @var{X}. This function is available under the name
1521 @code{BESJ0} as a GNU extension.
1522
1523 @item @emph{Standard}:
1524 Fortran 2008 and later
1525
1526 @item @emph{Class}:
1527 Elemental function
1528
1529 @item @emph{Syntax}:
1530 @code{RESULT = BESSEL_J0(X)}
1531
1532 @item @emph{Arguments}:
1533 @multitable @columnfractions .15 .70
1534 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1535 @end multitable
1536
1537 @item @emph{Return value}:
1538 The return value is of type @code{REAL} and lies in the
1539 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1540 kind as @var{X}.
1541
1542 @item @emph{Example}:
1543 @smallexample
1544 program test_besj0
1545   real(8) :: x = 0.0_8
1546   x = bessel_j0(x)
1547 end program test_besj0
1548 @end smallexample
1549
1550 @item @emph{Specific names}:
1551 @multitable @columnfractions .20 .20 .20 .25
1552 @item Name            @tab Argument          @tab Return type       @tab Standard
1553 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1554 @end multitable
1555 @end table
1556
1557
1558
1559 @node BESSEL_J1
1560 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1561 @fnindex BESSEL_J1
1562 @fnindex BESJ1
1563 @fnindex DBESJ1
1564 @cindex Bessel function, first kind
1565
1566 @table @asis
1567 @item @emph{Description}:
1568 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1569 order 1 of @var{X}. This function is available under the name
1570 @code{BESJ1} as a GNU extension.
1571
1572 @item @emph{Standard}:
1573 Fortran 2008
1574
1575 @item @emph{Class}:
1576 Elemental function
1577
1578 @item @emph{Syntax}:
1579 @code{RESULT = BESSEL_J1(X)}
1580
1581 @item @emph{Arguments}:
1582 @multitable @columnfractions .15 .70
1583 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1584 @end multitable
1585
1586 @item @emph{Return value}:
1587 The return value is of type @code{REAL} and it lies in the
1588 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1589 kind as @var{X}.
1590
1591 @item @emph{Example}:
1592 @smallexample
1593 program test_besj1
1594   real(8) :: x = 1.0_8
1595   x = bessel_j1(x)
1596 end program test_besj1
1597 @end smallexample
1598
1599 @item @emph{Specific names}:
1600 @multitable @columnfractions .20 .20 .20 .25
1601 @item Name            @tab Argument          @tab Return type       @tab Standard
1602 @item @code{DBESJ1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1603 @end multitable
1604 @end table
1605
1606
1607
1608 @node BESSEL_JN
1609 @section @code{BESSEL_JN} --- Bessel function of the first kind
1610 @fnindex BESSEL_JN
1611 @fnindex BESJN
1612 @fnindex DBESJN
1613 @cindex Bessel function, first kind
1614
1615 @table @asis
1616 @item @emph{Description}:
1617 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1618 order @var{N} of @var{X}. This function is available under the name
1619 @code{BESJN} as a GNU extension.
1620
1621 If both arguments are arrays, their ranks and shapes shall conform.
1622
1623 @item @emph{Standard}:
1624 Fortran 2008 and later
1625
1626 @item @emph{Class}:
1627 Elemental function
1628
1629 @item @emph{Syntax}:
1630 @code{RESULT = BESSEL_JN(N, X)}
1631
1632 @item @emph{Arguments}:
1633 @multitable @columnfractions .15 .70
1634 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1635 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL}.
1636 @end multitable
1637
1638 @item @emph{Return value}:
1639 The return value is a scalar of type @code{REAL}. It has the same
1640 kind as @var{X}.
1641
1642 @item @emph{Example}:
1643 @smallexample
1644 program test_besjn
1645   real(8) :: x = 1.0_8
1646   x = bessel_jn(5,x)
1647 end program test_besjn
1648 @end smallexample
1649
1650 @item @emph{Specific names}:
1651 @multitable @columnfractions .20 .20 .20 .25
1652 @item Name                @tab Argument            @tab Return type       @tab Standard
1653 @item @code{DBESJN(N, X)} @tab @code{INTEGER N}    @tab @code{REAL(8)}    @tab GNU extension
1654 @item                     @tab @code{REAL(8) X}    @tab                   @tab
1655 @end multitable
1656 @end table
1657
1658
1659
1660 @node BESSEL_Y0
1661 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1662 @fnindex BESSEL_Y0
1663 @fnindex BESY0
1664 @fnindex DBESY0
1665 @cindex Bessel function, second kind
1666
1667 @table @asis
1668 @item @emph{Description}:
1669 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1670 order 0 of @var{X}. This function is available under the name
1671 @code{BESY0} as a GNU extension.
1672
1673 @item @emph{Standard}:
1674 Fortran 2008 and later
1675
1676 @item @emph{Class}:
1677 Elemental function
1678
1679 @item @emph{Syntax}:
1680 @code{RESULT = BESSEL_Y0(X)}
1681
1682 @item @emph{Arguments}:
1683 @multitable @columnfractions .15 .70
1684 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1685 @end multitable
1686
1687 @item @emph{Return value}:
1688 The return value is a scalar of type @code{REAL}. It has the same
1689 kind as @var{X}.
1690
1691 @item @emph{Example}:
1692 @smallexample
1693 program test_besy0
1694   real(8) :: x = 0.0_8
1695   x = bessel_y0(x)
1696 end program test_besy0
1697 @end smallexample
1698
1699 @item @emph{Specific names}:
1700 @multitable @columnfractions .20 .20 .20 .25
1701 @item Name            @tab Argument          @tab Return type       @tab Standard
1702 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1703 @end multitable
1704 @end table
1705
1706
1707
1708 @node BESSEL_Y1
1709 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1710 @fnindex BESSEL_Y1
1711 @fnindex BESY1
1712 @fnindex DBESY1
1713 @cindex Bessel function, second kind
1714
1715 @table @asis
1716 @item @emph{Description}:
1717 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1718 order 1 of @var{X}. This function is available under the name
1719 @code{BESY1} as a GNU extension.
1720
1721 @item @emph{Standard}:
1722 Fortran 2008 and later
1723
1724 @item @emph{Class}:
1725 Elemental function
1726
1727 @item @emph{Syntax}:
1728 @code{RESULT = BESSEL_Y1(X)}
1729
1730 @item @emph{Arguments}:
1731 @multitable @columnfractions .15 .70
1732 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1733 @end multitable
1734
1735 @item @emph{Return value}:
1736 The return value is a scalar of type @code{REAL}. It has the same
1737 kind as @var{X}.
1738
1739 @item @emph{Example}:
1740 @smallexample
1741 program test_besy1
1742   real(8) :: x = 1.0_8
1743   x = bessel_y1(x)
1744 end program test_besy1
1745 @end smallexample
1746
1747 @item @emph{Specific names}:
1748 @multitable @columnfractions .20 .20 .20 .25
1749 @item Name            @tab Argument          @tab Return type       @tab Standard
1750 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1751 @end multitable
1752 @end table
1753
1754
1755
1756 @node BESSEL_YN
1757 @section @code{BESSEL_YN} --- Bessel function of the second kind
1758 @fnindex BESSEL_YN
1759 @fnindex BESYN
1760 @fnindex DBESYN
1761 @cindex Bessel function, second kind
1762
1763 @table @asis
1764 @item @emph{Description}:
1765 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1766 order @var{N} of @var{X}. This function is available under the name
1767 @code{BESYN} as a GNU extension.
1768
1769 If both arguments are arrays, their ranks and shapes shall conform.
1770
1771 @item @emph{Standard}:
1772 Fortran 2008 and later
1773
1774 @item @emph{Class}:
1775 Elemental function
1776
1777 @item @emph{Syntax}:
1778 @code{RESULT = BESSEL_YN(N, X)}
1779
1780 @item @emph{Arguments}:
1781 @multitable @columnfractions .15 .70
1782 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1783 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL}.
1784 @end multitable
1785
1786 @item @emph{Return value}:
1787 The return value is a scalar of type @code{REAL}. It has the same
1788 kind as @var{X}.
1789
1790 @item @emph{Example}:
1791 @smallexample
1792 program test_besyn
1793   real(8) :: x = 1.0_8
1794   x = bessel_yn(5,x)
1795 end program test_besyn
1796 @end smallexample
1797
1798 @item @emph{Specific names}:
1799 @multitable @columnfractions .20 .20 .20 .25
1800 @item Name               @tab Argument            @tab Return type     @tab Standard
1801 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
1802 @item                    @tab @code{REAL(8)    X} @tab                 @tab 
1803 @end multitable
1804 @end table
1805
1806
1807
1808 @node BIT_SIZE
1809 @section @code{BIT_SIZE} --- Bit size inquiry function
1810 @fnindex BIT_SIZE
1811 @cindex bits, number of
1812 @cindex size of a variable, in bits
1813
1814 @table @asis
1815 @item @emph{Description}:
1816 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1817 represented by the type of @var{I}.  The result of @code{BIT_SIZE(I)} is
1818 independent of the actual value of @var{I}.
1819
1820 @item @emph{Standard}:
1821 Fortran 95 and later
1822
1823 @item @emph{Class}:
1824 Inquiry function
1825
1826 @item @emph{Syntax}:
1827 @code{RESULT = BIT_SIZE(I)}
1828
1829 @item @emph{Arguments}:
1830 @multitable @columnfractions .15 .70
1831 @item @var{I} @tab The type shall be @code{INTEGER}.
1832 @end multitable
1833
1834 @item @emph{Return value}:
1835 The return value is of type @code{INTEGER}
1836
1837 @item @emph{Example}:
1838 @smallexample
1839 program test_bit_size
1840     integer :: i = 123
1841     integer :: size
1842     size = bit_size(i)
1843     print *, size
1844 end program test_bit_size
1845 @end smallexample
1846 @end table
1847
1848
1849
1850 @node BTEST
1851 @section @code{BTEST} --- Bit test function
1852 @fnindex BTEST
1853 @cindex bits, testing
1854
1855 @table @asis
1856 @item @emph{Description}:
1857 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1858 in @var{I} is set.  The counting of the bits starts at 0.
1859
1860 @item @emph{Standard}:
1861 Fortran 95 and later
1862
1863 @item @emph{Class}:
1864 Elemental function
1865
1866 @item @emph{Syntax}:
1867 @code{RESULT = BTEST(I, POS)}
1868
1869 @item @emph{Arguments}:
1870 @multitable @columnfractions .15 .70
1871 @item @var{I} @tab The type shall be @code{INTEGER}.
1872 @item @var{POS} @tab The type shall be @code{INTEGER}.
1873 @end multitable
1874
1875 @item @emph{Return value}:
1876 The return value is of type @code{LOGICAL}
1877
1878 @item @emph{Example}:
1879 @smallexample
1880 program test_btest
1881     integer :: i = 32768 + 1024 + 64
1882     integer :: pos
1883     logical :: bool
1884     do pos=0,16
1885         bool = btest(i, pos) 
1886         print *, pos, bool
1887     end do
1888 end program test_btest
1889 @end smallexample
1890 @end table
1891
1892
1893 @node C_ASSOCIATED
1894 @section @code{C_ASSOCIATED} --- Status of a C pointer
1895 @fnindex C_ASSOCIATED
1896 @cindex association status, C pointer
1897 @cindex pointer, C association status
1898
1899 @table @asis
1900 @item @emph{Description}:
1901 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1902 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1903
1904 @item @emph{Standard}:
1905 Fortran 2003 and later
1906
1907 @item @emph{Class}:
1908 Inquiry function
1909
1910 @item @emph{Syntax}:
1911 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1912
1913 @item @emph{Arguments}:
1914 @multitable @columnfractions .15 .70
1915 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1916 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1917 @end multitable
1918
1919 @item @emph{Return value}:
1920 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1921 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1922 point to different addresses.
1923
1924 @item @emph{Example}:
1925 @smallexample
1926 subroutine association_test(a,b)
1927   use iso_c_binding, only: c_associated, c_loc, c_ptr
1928   implicit none
1929   real, pointer :: a
1930   type(c_ptr) :: b
1931   if(c_associated(b, c_loc(a))) &
1932      stop 'b and a do not point to same target'
1933 end subroutine association_test
1934 @end smallexample
1935
1936 @item @emph{See also}:
1937 @ref{C_LOC}, @ref{C_FUNLOC}
1938 @end table
1939
1940
1941 @node C_FUNLOC
1942 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1943 @fnindex C_FUNLOC
1944 @cindex pointer, C address of procedures
1945
1946 @table @asis
1947 @item @emph{Description}:
1948 @code{C_FUNLOC(x)} determines the C address of the argument.
1949
1950 @item @emph{Standard}:
1951 Fortran 2003 and later
1952
1953 @item @emph{Class}:
1954 Inquiry function
1955
1956 @item @emph{Syntax}:
1957 @code{RESULT = C_FUNLOC(x)}
1958
1959 @item @emph{Arguments}:
1960 @multitable @columnfractions .15 .70
1961 @item @var{x} @tab Interoperable function or pointer to such function.
1962 @end multitable
1963
1964 @item @emph{Return value}:
1965 The return value is of type @code{C_FUNPTR} and contains the C address
1966 of the argument.
1967
1968 @item @emph{Example}:
1969 @smallexample
1970 module x
1971   use iso_c_binding
1972   implicit none
1973 contains
1974   subroutine sub(a) bind(c)
1975     real(c_float) :: a
1976     a = sqrt(a)+5.0
1977   end subroutine sub
1978 end module x
1979 program main
1980   use iso_c_binding
1981   use x
1982   implicit none
1983   interface
1984     subroutine my_routine(p) bind(c,name='myC_func')
1985       import :: c_funptr
1986       type(c_funptr), intent(in) :: p
1987     end subroutine
1988   end interface
1989   call my_routine(c_funloc(sub))
1990 end program main
1991 @end smallexample
1992
1993 @item @emph{See also}:
1994 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1995 @end table
1996
1997
1998 @node C_F_PROCPOINTER
1999 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2000 @fnindex C_F_PROCPOINTER
2001 @cindex pointer, C address of pointers
2002
2003 @table @asis
2004 @item @emph{Description}:
2005 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2006 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2007
2008 @item @emph{Standard}:
2009 Fortran 2003 and later
2010
2011 @item @emph{Class}:
2012 Subroutine
2013
2014 @item @emph{Syntax}:
2015 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2016
2017 @item @emph{Arguments}:
2018 @multitable @columnfractions .15 .70
2019 @item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
2020 @code{INTENT(IN)}.
2021 @item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
2022 @code{INTENT(OUT)}.
2023 @end multitable
2024
2025 @item @emph{Example}:
2026 @smallexample
2027 program main
2028   use iso_c_binding
2029   implicit none
2030   abstract interface
2031     function func(a)
2032       import :: c_float
2033       real(c_float), intent(in) :: a
2034       real(c_float) :: func
2035     end function
2036   end interface
2037   interface
2038      function getIterFunc() bind(c,name="getIterFunc")
2039        import :: c_funptr
2040        type(c_funptr) :: getIterFunc
2041      end function
2042   end interface
2043   type(c_funptr) :: cfunptr
2044   procedure(func), pointer :: myFunc
2045   cfunptr = getIterFunc()
2046   call c_f_procpointer(cfunptr, myFunc)
2047 end program main
2048 @end smallexample
2049
2050 @item @emph{See also}:
2051 @ref{C_LOC}, @ref{C_F_POINTER}
2052 @end table
2053
2054
2055 @node C_F_POINTER
2056 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2057 @fnindex C_F_POINTER
2058 @cindex pointer, convert C to Fortran
2059
2060 @table @asis
2061 @item @emph{Description}:
2062 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2063 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2064 shape.
2065
2066 @item @emph{Standard}:
2067 Fortran 2003 and later
2068
2069 @item @emph{Class}:
2070 Subroutine
2071
2072 @item @emph{Syntax}:
2073 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2074
2075 @item @emph{Arguments}:
2076 @multitable @columnfractions .15 .70
2077 @item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
2078 @code{INTENT(IN)}.
2079 @item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
2080 @code{INTENT(OUT)}.
2081 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2082 with @code{INTENT(IN)}. It shall be present
2083 if and only if @var{fptr} is an array. The size
2084 must be equal to the rank of @var{fptr}.
2085 @end multitable
2086
2087 @item @emph{Example}:
2088 @smallexample
2089 program main
2090   use iso_c_binding
2091   implicit none
2092   interface
2093     subroutine my_routine(p) bind(c,name='myC_func')
2094       import :: c_ptr
2095       type(c_ptr), intent(out) :: p
2096     end subroutine
2097   end interface
2098   type(c_ptr) :: cptr
2099   real,pointer :: a(:)
2100   call my_routine(cptr)
2101   call c_f_pointer(cptr, a, [12])
2102 end program main
2103 @end smallexample
2104
2105 @item @emph{See also}:
2106 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2107 @end table
2108
2109
2110 @node C_LOC
2111 @section @code{C_LOC} --- Obtain the C address of an object
2112 @fnindex C_LOC
2113 @cindex procedure pointer, convert C to Fortran
2114
2115 @table @asis
2116 @item @emph{Description}:
2117 @code{C_LOC(X)} determines the C address of the argument.
2118
2119 @item @emph{Standard}:
2120 Fortran 2003 and later
2121
2122 @item @emph{Class}:
2123 Inquiry function
2124
2125 @item @emph{Syntax}:
2126 @code{RESULT = C_LOC(X)}
2127
2128 @item @emph{Arguments}:
2129 @multitable @columnfractions .15 .70
2130 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2131 or allocated allocatable variable with @code{TARGET} attribute.
2132 @end multitable
2133
2134 @item @emph{Return value}:
2135 The return value is of type @code{C_PTR} and contains the C address
2136 of the argument.
2137
2138 @item @emph{Example}:
2139 @smallexample
2140 subroutine association_test(a,b)
2141   use iso_c_binding, only: c_associated, c_loc, c_ptr
2142   implicit none
2143   real, pointer :: a
2144   type(c_ptr) :: b
2145   if(c_associated(b, c_loc(a))) &
2146      stop 'b and a do not point to same target'
2147 end subroutine association_test
2148 @end smallexample
2149
2150 @item @emph{See also}:
2151 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2152 @end table
2153
2154
2155 @node C_SIZEOF
2156 @section @code{C_SIZEOF} --- Size in bytes of an expression
2157 @fnindex C_SIZEOF
2158 @cindex expression size
2159 @cindex size of an expression
2160
2161 @table @asis
2162 @item @emph{Description}:
2163 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2164 expression @code{X} occupies.
2165
2166 @item @emph{Standard}:
2167 Fortran 2008
2168
2169 @item @emph{Class}:
2170 Intrinsic function
2171
2172 @item @emph{Syntax}:
2173 @code{N = C_SIZEOF(X)}
2174
2175 @item @emph{Arguments}:
2176 @multitable @columnfractions .15 .70
2177 @item @var{X} @tab The argument shall be of any type, rank or shape.
2178 @end multitable
2179
2180 @item @emph{Return value}:
2181 The return value is of type integer and of the system-dependent kind
2182 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2183 number of bytes occupied by the argument.  If the argument has the
2184 @code{POINTER} attribute, the number of bytes of the storage area pointed
2185 to is returned.  If the argument is of a derived type with @code{POINTER}
2186 or @code{ALLOCATABLE} components, the return value doesn't account for
2187 the sizes of the data pointed to by these components.
2188
2189 @item @emph{Example}:
2190 @smallexample
2191    use iso_c_binding
2192    integer(c_int) :: i
2193    real(c_float) :: r, s(5)
2194    print *, (c_sizeof(s)/c_sizeof(r) == 5)
2195    end
2196 @end smallexample
2197 The example will print @code{.TRUE.} unless you are using a platform
2198 where default @code{REAL} variables are unusually padded.
2199
2200 @item @emph{See also}:
2201 @ref{SIZEOF}
2202 @end table
2203
2204
2205 @node CEILING
2206 @section @code{CEILING} --- Integer ceiling function
2207 @fnindex CEILING
2208 @cindex ceiling
2209 @cindex rounding, ceiling
2210
2211 @table @asis
2212 @item @emph{Description}:
2213 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2214
2215 @item @emph{Standard}:
2216 Fortran 95 and later
2217
2218 @item @emph{Class}:
2219 Elemental function
2220
2221 @item @emph{Syntax}:
2222 @code{RESULT = CEILING(A [, KIND])}
2223
2224 @item @emph{Arguments}:
2225 @multitable @columnfractions .15 .70
2226 @item @var{A} @tab The type shall be @code{REAL}.
2227 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2228 expression indicating the kind parameter of the result.
2229 @end multitable
2230
2231 @item @emph{Return value}:
2232 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2233 and a default-kind @code{INTEGER} otherwise.
2234
2235 @item @emph{Example}:
2236 @smallexample
2237 program test_ceiling
2238     real :: x = 63.29
2239     real :: y = -63.59
2240     print *, ceiling(x) ! returns 64
2241     print *, ceiling(y) ! returns -63
2242 end program test_ceiling
2243 @end smallexample
2244
2245 @item @emph{See also}:
2246 @ref{FLOOR}, @ref{NINT}
2247
2248 @end table
2249
2250
2251
2252 @node CHAR
2253 @section @code{CHAR} --- Character conversion function
2254 @fnindex CHAR
2255 @cindex conversion, to character
2256
2257 @table @asis
2258 @item @emph{Description}:
2259 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2260
2261 @item @emph{Standard}:
2262 Fortran 77 and later
2263
2264 @item @emph{Class}:
2265 Elemental function
2266
2267 @item @emph{Syntax}:
2268 @code{RESULT = CHAR(I [, KIND])}
2269
2270 @item @emph{Arguments}:
2271 @multitable @columnfractions .15 .70
2272 @item @var{I} @tab The type shall be @code{INTEGER}.
2273 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2274 expression indicating the kind parameter of the result.
2275 @end multitable
2276
2277 @item @emph{Return value}:
2278 The return value is of type @code{CHARACTER(1)}
2279
2280 @item @emph{Example}:
2281 @smallexample
2282 program test_char
2283     integer :: i = 74
2284     character(1) :: c
2285     c = char(i)
2286     print *, i, c ! returns 'J'
2287 end program test_char
2288 @end smallexample
2289
2290 @item @emph{Note}:
2291 See @ref{ICHAR} for a discussion of converting between numerical values
2292 and formatted string representations.
2293
2294 @item @emph{See also}:
2295 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2296
2297 @end table
2298
2299
2300
2301 @node CHDIR
2302 @section @code{CHDIR} --- Change working directory
2303 @fnindex CHDIR
2304 @cindex system, working directory
2305
2306 @table @asis
2307 @item @emph{Description}:
2308 Change current working directory to a specified path.
2309
2310 This intrinsic is provided in both subroutine and function forms; however,
2311 only one form can be used in any given program unit.
2312
2313 @item @emph{Standard}:
2314 GNU extension
2315
2316 @item @emph{Class}:
2317 Subroutine, function
2318
2319 @item @emph{Syntax}:
2320 @multitable @columnfractions .80
2321 @item @code{CALL CHDIR(NAME [, STATUS])}
2322 @item @code{STATUS = CHDIR(NAME)}
2323 @end multitable
2324
2325 @item @emph{Arguments}:
2326 @multitable @columnfractions .15 .70
2327 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
2328 kind and shall specify a valid path within the file system.
2329 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2330 kind.  Returns 0 on success, and a system specific and nonzero error code
2331 otherwise.
2332 @end multitable
2333
2334 @item @emph{Example}:
2335 @smallexample
2336 PROGRAM test_chdir
2337   CHARACTER(len=255) :: path
2338   CALL getcwd(path)
2339   WRITE(*,*) TRIM(path)
2340   CALL chdir("/tmp")
2341   CALL getcwd(path)
2342   WRITE(*,*) TRIM(path)
2343 END PROGRAM
2344 @end smallexample
2345
2346 @item @emph{See also}:
2347 @ref{GETCWD}
2348 @end table
2349
2350
2351
2352 @node CHMOD
2353 @section @code{CHMOD} --- Change access permissions of files
2354 @fnindex CHMOD
2355 @cindex file system, change access mode
2356
2357 @table @asis
2358 @item @emph{Description}:
2359 @code{CHMOD} changes the permissions of a file. This function invokes
2360 @code{/bin/chmod} and might therefore not work on all platforms.
2361
2362 This intrinsic is provided in both subroutine and function forms; however,
2363 only one form can be used in any given program unit.
2364
2365 @item @emph{Standard}:
2366 GNU extension
2367
2368 @item @emph{Class}:
2369 Subroutine, function
2370
2371 @item @emph{Syntax}:
2372 @multitable @columnfractions .80
2373 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2374 @item @code{STATUS = CHMOD(NAME, MODE)}
2375 @end multitable
2376
2377 @item @emph{Arguments}:
2378 @multitable @columnfractions .15 .70
2379
2380 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2381 file name. Trailing blanks are ignored unless the character
2382 @code{achar(0)} is present, then all characters up to and excluding
2383 @code{achar(0)} are used as the file name.
2384
2385 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2386 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2387 argument of @code{/bin/chmod}.
2388
2389 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2390 @code{0} on success and nonzero otherwise.
2391 @end multitable
2392
2393 @item @emph{Return value}:
2394 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2395 otherwise.
2396
2397 @item @emph{Example}:
2398 @code{CHMOD} as subroutine
2399 @smallexample
2400 program chmod_test
2401   implicit none
2402   integer :: status
2403   call chmod('test.dat','u+x',status)
2404   print *, 'Status: ', status
2405 end program chmod_test
2406 @end smallexample
2407 @code{CHMOD} as function:
2408 @smallexample
2409 program chmod_test
2410   implicit none
2411   integer :: status
2412   status = chmod('test.dat','u+x')
2413   print *, 'Status: ', status
2414 end program chmod_test
2415 @end smallexample
2416
2417 @end table
2418
2419
2420
2421 @node CMPLX
2422 @section @code{CMPLX} --- Complex conversion function
2423 @fnindex CMPLX
2424 @cindex complex numbers, conversion to
2425 @cindex conversion, to complex
2426
2427 @table @asis
2428 @item @emph{Description}:
2429 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2430 the real component.  If @var{Y} is present it is converted to the imaginary
2431 component.  If @var{Y} is not present then the imaginary component is set to
2432 0.0.  If @var{X} is complex then @var{Y} must not be present.
2433
2434 @item @emph{Standard}:
2435 Fortran 77 and later
2436
2437 @item @emph{Class}:
2438 Elemental function
2439
2440 @item @emph{Syntax}:
2441 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2442
2443 @item @emph{Arguments}:
2444 @multitable @columnfractions .15 .70
2445 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2446 or @code{COMPLEX}.
2447 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2448 @code{COMPLEX}.)  May be @code{INTEGER} or @code{REAL}.
2449 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2450 expression indicating the kind parameter of the result.
2451 @end multitable
2452
2453 @item @emph{Return value}:
2454 The return value is of @code{COMPLEX} type, with a kind equal to
2455 @var{KIND} if it is specified.  If @var{KIND} is not specified, the
2456 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2457 @var{X} and @var{Y}. 
2458
2459 @item @emph{Example}:
2460 @smallexample
2461 program test_cmplx
2462     integer :: i = 42
2463     real :: x = 3.14
2464     complex :: z
2465     z = cmplx(i, x)
2466     print *, z, cmplx(x)
2467 end program test_cmplx
2468 @end smallexample
2469
2470 @item @emph{See also}:
2471 @ref{COMPLEX}
2472 @end table
2473
2474
2475
2476 @node COMMAND_ARGUMENT_COUNT
2477 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2478 @fnindex COMMAND_ARGUMENT_COUNT
2479 @cindex command-line arguments
2480 @cindex command-line arguments, number of
2481 @cindex arguments, to program
2482
2483 @table @asis
2484 @item @emph{Description}:
2485 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2486 command line when the containing program was invoked.
2487
2488 @item @emph{Standard}:
2489 Fortran 2003 and later
2490
2491 @item @emph{Class}:
2492 Inquiry function
2493
2494 @item @emph{Syntax}:
2495 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2496
2497 @item @emph{Arguments}:
2498 @multitable @columnfractions .15 .70
2499 @item None
2500 @end multitable
2501
2502 @item @emph{Return value}:
2503 The return value is an @code{INTEGER} of default kind.
2504
2505 @item @emph{Example}:
2506 @smallexample
2507 program test_command_argument_count
2508     integer :: count
2509     count = command_argument_count()
2510     print *, count
2511 end program test_command_argument_count
2512 @end smallexample
2513
2514 @item @emph{See also}:
2515 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2516 @end table
2517
2518
2519
2520 @node COMPLEX
2521 @section @code{COMPLEX} --- Complex conversion function
2522 @fnindex COMPLEX
2523 @cindex complex numbers, conversion to
2524 @cindex conversion, to complex
2525
2526 @table @asis
2527 @item @emph{Description}:
2528 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2529 to the real component and @var{Y} is converted to the imaginary
2530 component.
2531
2532 @item @emph{Standard}:
2533 GNU extension
2534
2535 @item @emph{Class}:
2536 Elemental function
2537
2538 @item @emph{Syntax}:
2539 @code{RESULT = COMPLEX(X, Y)}
2540
2541 @item @emph{Arguments}:
2542 @multitable @columnfractions .15 .70
2543 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2544 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2545 @end multitable
2546
2547 @item @emph{Return value}:
2548 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2549 value is of default @code{COMPLEX} type.
2550
2551 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2552 type and one is of @code{INTEGER} type, then the return value is of
2553 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2554 argument with the highest precision.  
2555
2556 @item @emph{Example}:
2557 @smallexample
2558 program test_complex
2559     integer :: i = 42
2560     real :: x = 3.14
2561     print *, complex(i, x)
2562 end program test_complex
2563 @end smallexample
2564
2565 @item @emph{See also}:
2566 @ref{CMPLX}
2567 @end table
2568
2569
2570
2571 @node CONJG
2572 @section @code{CONJG} --- Complex conjugate function 
2573 @fnindex CONJG
2574 @fnindex DCONJG
2575 @cindex complex conjugate
2576
2577 @table @asis
2578 @item @emph{Description}:
2579 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2580 then the result is @code{(x, -y)}
2581
2582 @item @emph{Standard}:
2583 Fortran 77 and later, has overloads that are GNU extensions
2584
2585 @item @emph{Class}:
2586 Elemental function
2587
2588 @item @emph{Syntax}:
2589 @code{Z = CONJG(Z)}
2590
2591 @item @emph{Arguments}:
2592 @multitable @columnfractions .15 .70
2593 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2594 @end multitable
2595
2596 @item @emph{Return value}:
2597 The return value is of type @code{COMPLEX}.
2598
2599 @item @emph{Example}:
2600 @smallexample
2601 program test_conjg
2602     complex :: z = (2.0, 3.0)
2603     complex(8) :: dz = (2.71_8, -3.14_8)
2604     z= conjg(z)
2605     print *, z
2606     dz = dconjg(dz)
2607     print *, dz
2608 end program test_conjg
2609 @end smallexample
2610
2611 @item @emph{Specific names}:
2612 @multitable @columnfractions .20 .20 .20 .25
2613 @item Name             @tab Argument             @tab Return type          @tab Standard
2614 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)}    @tab GNU extension
2615 @end multitable
2616 @end table
2617
2618
2619
2620 @node COS
2621 @section @code{COS} --- Cosine function 
2622 @fnindex COS
2623 @fnindex DCOS
2624 @fnindex CCOS
2625 @fnindex ZCOS
2626 @fnindex CDCOS
2627 @cindex trigonometric function, cosine
2628 @cindex cosine
2629
2630 @table @asis
2631 @item @emph{Description}:
2632 @code{COS(X)} computes the cosine of @var{X}.
2633
2634 @item @emph{Standard}:
2635 Fortran 77 and later, has overloads that are GNU extensions
2636
2637 @item @emph{Class}:
2638 Elemental function
2639
2640 @item @emph{Syntax}:
2641 @code{RESULT = COS(X)}
2642
2643 @item @emph{Arguments}:
2644 @multitable @columnfractions .15 .70
2645 @item @var{X} @tab The type shall be @code{REAL} or
2646 @code{COMPLEX}.
2647 @end multitable
2648
2649 @item @emph{Return value}:
2650 The return value is of the same type and kind as @var{X}. The real part
2651 of the result is in radians. If @var{X} is of the type @code{REAL},
2652 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2653
2654 @item @emph{Example}:
2655 @smallexample
2656 program test_cos
2657   real :: x = 0.0
2658   x = cos(x)
2659 end program test_cos
2660 @end smallexample
2661
2662 @item @emph{Specific names}:
2663 @multitable @columnfractions .20 .20 .20 .25
2664 @item Name            @tab Argument            @tab Return type       @tab Standard
2665 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
2666 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2667 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2668 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2669 @end multitable
2670
2671 @item @emph{See also}:
2672 Inverse function: @ref{ACOS}
2673
2674 @end table
2675
2676
2677
2678 @node COSH
2679 @section @code{COSH} --- Hyperbolic cosine function 
2680 @fnindex COSH
2681 @fnindex DCOSH
2682 @cindex hyperbolic cosine
2683 @cindex hyperbolic function, cosine
2684 @cindex cosine, hyperbolic
2685
2686 @table @asis
2687 @item @emph{Description}:
2688 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2689
2690 @item @emph{Standard}:
2691 Fortran 77 and later, for a complex argument Fortran 2008 or later
2692
2693 @item @emph{Class}:
2694 Elemental function
2695
2696 @item @emph{Syntax}:
2697 @code{X = COSH(X)}
2698
2699 @item @emph{Arguments}:
2700 @multitable @columnfractions .15 .70
2701 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2702 @end multitable
2703
2704 @item @emph{Return value}:
2705 The return value has same type and kind as @var{X}. If @var{X} is
2706 complex, the imaginary part of the result is in radians. If @var{X}
2707 is @code{REAL}, the return value has a lower bound of one,
2708 @math{\cosh (x) \geq 1}.
2709
2710 @item @emph{Example}:
2711 @smallexample
2712 program test_cosh
2713   real(8) :: x = 1.0_8
2714   x = cosh(x)
2715 end program test_cosh
2716 @end smallexample
2717
2718 @item @emph{Specific names}:
2719 @multitable @columnfractions .20 .20 .20 .25
2720 @item Name            @tab Argument          @tab Return type       @tab Standard
2721 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
2722 @end multitable
2723
2724 @item @emph{See also}:
2725 Inverse function: @ref{ACOSH}
2726
2727 @end table
2728
2729
2730
2731 @node COUNT
2732 @section @code{COUNT} --- Count function
2733 @fnindex COUNT
2734 @cindex array, conditionally count elements
2735 @cindex array, element counting
2736 @cindex array, number of elements
2737
2738 @table @asis
2739 @item @emph{Description}:
2740
2741 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2742 or, if the @var{DIM} argument is supplied, counts the number of
2743 elements along each row of the array in the @var{DIM} direction.
2744 If the array has zero size, or all of the elements of @var{MASK} are
2745 @code{.FALSE.}, then the result is @code{0}.
2746
2747 @item @emph{Standard}:
2748 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2749
2750 @item @emph{Class}:
2751 Transformational function
2752
2753 @item @emph{Syntax}:
2754 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2755
2756 @item @emph{Arguments}:
2757 @multitable @columnfractions .15 .70
2758 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2759 @item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
2760 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2761 expression indicating the kind parameter of the result.
2762 @end multitable
2763
2764 @item @emph{Return value}:
2765 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2766 @var{KIND} is absent, the return value is of default integer kind.
2767 If @var{DIM} is present, the result is an array with a rank one less
2768 than the rank of @var{ARRAY}, and a size corresponding to the shape
2769 of @var{ARRAY} with the @var{DIM} dimension removed.
2770
2771 @item @emph{Example}:
2772 @smallexample
2773 program test_count
2774     integer, dimension(2,3) :: a, b
2775     logical, dimension(2,3) :: mask
2776     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2777     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2778     print '(3i3)', a(1,:)
2779     print '(3i3)', a(2,:)
2780     print *
2781     print '(3i3)', b(1,:)
2782     print '(3i3)', b(2,:)
2783     print *
2784     mask = a.ne.b
2785     print '(3l3)', mask(1,:)
2786     print '(3l3)', mask(2,:)
2787     print *
2788     print '(3i3)', count(mask)
2789     print *
2790     print '(3i3)', count(mask, 1)
2791     print *
2792     print '(3i3)', count(mask, 2)
2793 end program test_count
2794 @end smallexample
2795 @end table
2796
2797
2798
2799 @node CPU_TIME
2800 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2801 @fnindex CPU_TIME
2802 @cindex time, elapsed
2803
2804 @table @asis
2805 @item @emph{Description}:
2806 Returns a @code{REAL} value representing the elapsed CPU time in
2807 seconds.  This is useful for testing segments of code to determine
2808 execution time.
2809
2810 If a time source is available, time will be reported with microsecond
2811 resolution. If no time source is available, @var{TIME} is set to
2812 @code{-1.0}.
2813
2814 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2815 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2816 value is meaningless, only differences between subsequent calls to
2817 this subroutine, as shown in the example below, should be used.
2818
2819
2820 @item @emph{Standard}:
2821 Fortran 95 and later
2822
2823 @item @emph{Class}:
2824 Subroutine
2825
2826 @item @emph{Syntax}:
2827 @code{CALL CPU_TIME(TIME)}
2828
2829 @item @emph{Arguments}:
2830 @multitable @columnfractions .15 .70
2831 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2832 @end multitable
2833
2834 @item @emph{Return value}:
2835 None
2836
2837 @item @emph{Example}:
2838 @smallexample
2839 program test_cpu_time
2840     real :: start, finish
2841     call cpu_time(start)
2842         ! put code to test here
2843     call cpu_time(finish)
2844     print '("Time = ",f6.3," seconds.")',finish-start
2845 end program test_cpu_time
2846 @end smallexample
2847
2848 @item @emph{See also}:
2849 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2850 @end table
2851
2852
2853
2854 @node CSHIFT
2855 @section @code{CSHIFT} --- Circular shift elements of an array
2856 @fnindex CSHIFT
2857 @cindex array, shift circularly
2858 @cindex array, permutation
2859 @cindex array, rotate
2860
2861 @table @asis
2862 @item @emph{Description}:
2863 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2864 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
2865 taken to be @code{1}.  @var{DIM} is a scalar of type @code{INTEGER} in the
2866 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2867 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2868 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
2869 sections of @var{ARRAY} along the given dimension are shifted.  Elements
2870 shifted out one end of each rank one section are shifted back in the other end.
2871
2872 @item @emph{Standard}:
2873 Fortran 95 and later
2874
2875 @item @emph{Class}:
2876 Transformational function
2877
2878 @item @emph{Syntax}:
2879 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2880
2881 @item @emph{Arguments}:
2882 @multitable @columnfractions .15 .70
2883 @item @var{ARRAY}  @tab Shall be an array of any type.
2884 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
2885 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
2886 @end multitable
2887
2888 @item @emph{Return value}:
2889 Returns an array of same type and rank as the @var{ARRAY} argument.
2890
2891 @item @emph{Example}:
2892 @smallexample
2893 program test_cshift
2894     integer, dimension(3,3) :: a
2895     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2896     print '(3i3)', a(1,:)
2897     print '(3i3)', a(2,:)
2898     print '(3i3)', a(3,:)    
2899     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2900     print *
2901     print '(3i3)', a(1,:)
2902     print '(3i3)', a(2,:)
2903     print '(3i3)', a(3,:)
2904 end program test_cshift
2905 @end smallexample
2906 @end table
2907
2908
2909
2910 @node CTIME
2911 @section @code{CTIME} --- Convert a time into a string
2912 @fnindex CTIME
2913 @cindex time, conversion to string
2914 @cindex conversion, to string
2915
2916 @table @asis
2917 @item @emph{Description}:
2918 @code{CTIME} converts a system time value, such as returned by
2919 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2920
2921 This intrinsic is provided in both subroutine and function forms; however,
2922 only one form can be used in any given program unit.
2923
2924 @item @emph{Standard}:
2925 GNU extension
2926
2927 @item @emph{Class}:
2928 Subroutine, function
2929
2930 @item @emph{Syntax}:
2931 @multitable @columnfractions .80
2932 @item @code{CALL CTIME(TIME, RESULT)}.
2933 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2934 @end multitable
2935
2936 @item @emph{Arguments}:
2937 @multitable @columnfractions .15 .70
2938 @item @var{TIME}    @tab The type shall be of type @code{INTEGER(KIND=8)}.
2939 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
2940 of default kind.
2941 @end multitable
2942
2943 @item @emph{Return value}:
2944 The converted date and time as a string.
2945
2946 @item @emph{Example}:
2947 @smallexample
2948 program test_ctime
2949     integer(8) :: i
2950     character(len=30) :: date
2951     i = time8()
2952
2953     ! Do something, main part of the program
2954     
2955     call ctime(i,date)
2956     print *, 'Program was started on ', date
2957 end program test_ctime
2958 @end smallexample
2959
2960 @item @emph{See Also}:
2961 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2962 @end table
2963
2964
2965
2966 @node DATE_AND_TIME
2967 @section @code{DATE_AND_TIME} --- Date and time subroutine
2968 @fnindex DATE_AND_TIME
2969 @cindex date, current
2970 @cindex current date
2971 @cindex time, current
2972 @cindex current time
2973
2974 @table @asis
2975 @item @emph{Description}:
2976 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2977 time information from the real-time system clock.  @var{DATE} is
2978 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
2979 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2980 representing the difference with respect to Coordinated Universal Time (UTC).
2981 Unavailable time and date parameters return blanks.
2982
2983 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2984
2985 @multitable @columnfractions .15 .30 .40
2986 @item @tab @code{VALUE(1)}: @tab The year
2987 @item @tab @code{VALUE(2)}: @tab The month
2988 @item @tab @code{VALUE(3)}: @tab The day of the month
2989 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2990 @item @tab @code{VALUE(5)}: @tab The hour of the day
2991 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2992 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2993 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2994 @end multitable
2995
2996 @item @emph{Standard}:
2997 Fortran 95 and later
2998
2999 @item @emph{Class}:
3000 Subroutine
3001
3002 @item @emph{Syntax}:
3003 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3004
3005 @item @emph{Arguments}:
3006 @multitable @columnfractions .15 .70
3007 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3008 or larger, and of default kind.
3009 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3010 or larger, and of default kind.
3011 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3012 or larger, and of default kind.
3013 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3014 @end multitable
3015
3016 @item @emph{Return value}:
3017 None
3018
3019 @item @emph{Example}:
3020 @smallexample
3021 program test_time_and_date
3022     character(8)  :: date
3023     character(10) :: time
3024     character(5)  :: zone
3025     integer,dimension(8) :: values
3026     ! using keyword arguments
3027     call date_and_time(date,time,zone,values)
3028     call date_and_time(DATE=date,ZONE=zone)
3029     call date_and_time(TIME=time)
3030     call date_and_time(VALUES=values)
3031     print '(a,2x,a,2x,a)', date, time, zone
3032     print '(8i5))', values
3033 end program test_time_and_date
3034 @end smallexample
3035
3036 @item @emph{See also}:
3037 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3038 @end table
3039
3040
3041
3042 @node DBLE
3043 @section @code{DBLE} --- Double conversion function 
3044 @fnindex DBLE
3045 @cindex conversion, to real
3046
3047 @table @asis
3048 @item @emph{Description}:
3049 @code{DBLE(A)} Converts @var{A} to double precision real type.
3050
3051 @item @emph{Standard}:
3052 Fortran 77 and later
3053
3054 @item @emph{Class}:
3055 Elemental function
3056
3057 @item @emph{Syntax}:
3058 @code{RESULT = DBLE(A)}
3059
3060 @item @emph{Arguments}:
3061 @multitable @columnfractions .15 .70
3062 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3063 or @code{COMPLEX}.
3064 @end multitable
3065
3066 @item @emph{Return value}:
3067 The return value is of type double precision real.
3068
3069 @item @emph{Example}:
3070 @smallexample
3071 program test_dble
3072     real    :: x = 2.18
3073     integer :: i = 5
3074     complex :: z = (2.3,1.14)
3075     print *, dble(x), dble(i), dble(z)
3076 end program test_dble
3077 @end smallexample
3078
3079 @item @emph{See also}:
3080 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3081 @end table
3082
3083
3084
3085 @node DCMPLX
3086 @section @code{DCMPLX} --- Double complex conversion function
3087 @fnindex DCMPLX
3088 @cindex complex numbers, conversion to
3089 @cindex conversion, to complex
3090
3091 @table @asis
3092 @item @emph{Description}:
3093 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3094 converted to the real component.  If @var{Y} is present it is converted to the
3095 imaginary component.  If @var{Y} is not present then the imaginary component is
3096 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3097
3098 @item @emph{Standard}:
3099 GNU extension
3100
3101 @item @emph{Class}:
3102 Elemental function
3103
3104 @item @emph{Syntax}:
3105 @code{RESULT = DCMPLX(X [, Y])}
3106
3107 @item @emph{Arguments}:
3108 @multitable @columnfractions .15 .70
3109 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3110 or @code{COMPLEX}.
3111 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3112 @code{INTEGER} or @code{REAL}. 
3113 @end multitable
3114
3115 @item @emph{Return value}:
3116 The return value is of type @code{COMPLEX(8)}
3117
3118 @item @emph{Example}:
3119 @smallexample
3120 program test_dcmplx
3121     integer :: i = 42
3122     real :: x = 3.14
3123     complex :: z
3124     z = cmplx(i, x)
3125     print *, dcmplx(i)
3126     print *, dcmplx(x)
3127     print *, dcmplx(z)
3128     print *, dcmplx(x,i)
3129 end program test_dcmplx
3130 @end smallexample
3131 @end table
3132
3133
3134
3135 @node DFLOAT
3136 @section @code{DFLOAT} --- Double conversion function 
3137 @fnindex DFLOAT
3138 @cindex conversion, to real
3139
3140 @table @asis
3141 @item @emph{Description}:
3142 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3143
3144 @item @emph{Standard}:
3145 GNU extension
3146
3147 @item @emph{Class}:
3148 Elemental function
3149
3150 @item @emph{Syntax}:
3151 @code{RESULT = DFLOAT(A)}
3152
3153 @item @emph{Arguments}:
3154 @multitable @columnfractions .15 .70
3155 @item @var{A} @tab The type shall be @code{INTEGER}.
3156 @end multitable
3157
3158 @item @emph{Return value}:
3159 The return value is of type double precision real.
3160
3161 @item @emph{Example}:
3162 @smallexample
3163 program test_dfloat
3164     integer :: i = 5
3165     print *, dfloat(i)
3166 end program test_dfloat
3167 @end smallexample
3168
3169 @item @emph{See also}:
3170 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3171 @end table
3172
3173
3174
3175 @node DIGITS
3176 @section @code{DIGITS} --- Significant binary digits function
3177 @fnindex DIGITS
3178 @cindex model representation, significant digits
3179
3180 @table @asis
3181 @item @emph{Description}:
3182 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3183 model representation of @var{X}.  For example, on a system using a 32-bit
3184 floating point representation, a default real number would likely return 24.
3185
3186 @item @emph{Standard}:
3187 Fortran 95 and later
3188
3189 @item @emph{Class}:
3190 Inquiry function
3191
3192 @item @emph{Syntax}:
3193 @code{RESULT = DIGITS(X)}
3194
3195 @item @emph{Arguments}:
3196 @multitable @columnfractions .15 .70
3197 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3198 @end multitable
3199
3200 @item @emph{Return value}:
3201 The return value is of type @code{INTEGER}.
3202
3203 @item @emph{Example}:
3204 @smallexample
3205 program test_digits
3206     integer :: i = 12345
3207     real :: x = 3.143
3208     real(8) :: y = 2.33
3209     print *, digits(i)
3210     print *, digits(x)
3211     print *, digits(y)
3212 end program test_digits
3213 @end smallexample
3214 @end table
3215
3216
3217
3218 @node DIM
3219 @section @code{DIM} --- Positive difference
3220 @fnindex DIM
3221 @fnindex IDIM
3222 @fnindex DDIM
3223 @cindex positive difference
3224
3225 @table @asis
3226 @item @emph{Description}:
3227 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3228 otherwise returns zero.
3229
3230 @item @emph{Standard}:
3231 Fortran 77 and later
3232
3233 @item @emph{Class}:
3234 Elemental function
3235
3236 @item @emph{Syntax}:
3237 @code{RESULT = DIM(X, Y)}
3238
3239 @item @emph{Arguments}:
3240 @multitable @columnfractions .15 .70
3241 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3242 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3243 @end multitable
3244
3245 @item @emph{Return value}:
3246 The return value is of type @code{INTEGER} or @code{REAL}.
3247
3248 @item @emph{Example}:
3249 @smallexample
3250 program test_dim
3251     integer :: i
3252     real(8) :: x
3253     i = dim(4, 15)
3254     x = dim(4.345_8, 2.111_8)
3255     print *, i
3256     print *, x
3257 end program test_dim
3258 @end smallexample
3259
3260 @item @emph{Specific names}:
3261 @multitable @columnfractions .20 .20 .20 .25
3262 @item Name             @tab Argument              @tab Return type       @tab Standard
3263 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3264 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3265 @end multitable
3266 @end table
3267
3268
3269
3270 @node DOT_PRODUCT
3271 @section @code{DOT_PRODUCT} --- Dot product function
3272 @fnindex DOT_PRODUCT
3273 @cindex dot product
3274 @cindex vector product
3275 @cindex product, vector
3276
3277 @table @asis
3278 @item @emph{Description}:
3279 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3280 of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
3281 either numeric or logical and must be arrays of rank one and of equal size. If
3282 the vectors are @code{INTEGER} or @code{REAL}, the result is
3283 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3284 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3285 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.  
3286
3287 @item @emph{Standard}:
3288 Fortran 95 and later
3289
3290 @item @emph{Class}:
3291 Transformational function
3292
3293 @item @emph{Syntax}:
3294 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3295
3296 @item @emph{Arguments}:
3297 @multitable @columnfractions .15 .70
3298 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3299 @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.
3300 @end multitable
3301
3302 @item @emph{Return value}:
3303 If the arguments are numeric, the return value is a scalar of numeric type,
3304 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
3305 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3306
3307 @item @emph{Example}:
3308 @smallexample
3309 program test_dot_prod
3310     integer, dimension(3) :: a, b
3311     a = (/ 1, 2, 3 /)
3312     b = (/ 4, 5, 6 /)
3313     print '(3i3)', a
3314     print *
3315     print '(3i3)', b
3316     print *
3317     print *, dot_product(a,b)
3318 end program test_dot_prod
3319 @end smallexample
3320 @end table
3321
3322
3323
3324 @node DPROD
3325 @section @code{DPROD} --- Double product function
3326 @fnindex DPROD
3327 @cindex product, double-precision
3328
3329 @table @asis
3330 @item @emph{Description}:
3331 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3332
3333 @item @emph{Standard}:
3334 Fortran 77 and later
3335
3336 @item @emph{Class}:
3337 Elemental function
3338
3339 @item @emph{Syntax}:
3340 @code{RESULT = DPROD(X, Y)}
3341
3342 @item @emph{Arguments}:
3343 @multitable @columnfractions .15 .70
3344 @item @var{X} @tab The type shall be @code{REAL}.
3345 @item @var{Y} @tab The type shall be @code{REAL}.
3346 @end multitable
3347
3348 @item @emph{Return value}:
3349 The return value is of type @code{REAL(8)}.
3350
3351 @item @emph{Example}:
3352 @smallexample
3353 program test_dprod
3354     real :: x = 5.2
3355     real :: y = 2.3
3356     real(8) :: d
3357     d = dprod(x,y)
3358     print *, d
3359 end program test_dprod
3360 @end smallexample
3361 @end table
3362
3363
3364
3365 @node DREAL
3366 @section @code{DREAL} --- Double real part function
3367 @fnindex DREAL
3368 @cindex complex numbers, real part
3369
3370 @table @asis
3371 @item @emph{Description}:
3372 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3373
3374 @item @emph{Standard}:
3375 GNU extension
3376
3377 @item @emph{Class}:
3378 Elemental function
3379
3380 @item @emph{Syntax}:
3381 @code{RESULT = DREAL(A)}
3382
3383 @item @emph{Arguments}:
3384 @multitable @columnfractions .15 .70
3385 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3386 @end multitable
3387
3388 @item @emph{Return value}:
3389 The return value is of type @code{REAL(8)}.
3390
3391 @item @emph{Example}:
3392 @smallexample
3393 program test_dreal
3394     complex(8) :: z = (1.3_8,7.2_8)
3395     print *, dreal(z)
3396 end program test_dreal
3397 @end smallexample
3398
3399 @item @emph{See also}:
3400 @ref{AIMAG}
3401
3402 @end table
3403
3404
3405
3406 @node DTIME
3407 @section @code{DTIME} --- Execution time subroutine (or function)
3408 @fnindex DTIME
3409 @cindex time, elapsed
3410 @cindex elapsed time
3411
3412 @table @asis
3413 @item @emph{Description}:
3414 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3415 since the start of the process's execution in @var{TIME}.  @var{VALUES}
3416 returns the user and system components of this time in @code{VALUES(1)} and
3417 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3418 VALUES(2)}.
3419
3420 Subsequent invocations of @code{DTIME} return values accumulated since the
3421 previous invocation.
3422
3423 On some systems, the underlying timings are represented using types with
3424 sufficiently small limits that overflows (wrap around) are possible, such as
3425 32-bit types. Therefore, the values returned by this intrinsic might be, or
3426 become, negative, or numerically less than previous values, during a single
3427 run of the compiled program.
3428
3429 Please note, that this implementation is thread safe if used within OpenMP
3430 directives, i.e., its state will be consistent while called from multiple
3431 threads. However, if @code{DTIME} is called from multiple threads, the result
3432 is still the time since the last invocation. This may not give the intended
3433 results. If possible, use @code{CPU_TIME} instead.
3434
3435 This intrinsic is provided in both subroutine and function forms; however,
3436 only one form can be used in any given program unit.
3437
3438 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3439
3440 @multitable @columnfractions .15 .30 .40
3441 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3442 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3443 @item @tab @code{TIME}: @tab Run time since start in seconds.
3444 @end multitable
3445
3446 @item @emph{Standard}:
3447 GNU extension
3448
3449 @item @emph{Class}:
3450 Subroutine, function
3451
3452 @item @emph{Syntax}:
3453 @multitable @columnfractions .80
3454 @item @code{CALL DTIME(VALUES, TIME)}.
3455 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3456 @end multitable
3457
3458 @item @emph{Arguments}:
3459 @multitable @columnfractions .15 .70
3460 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3461 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3462 @end multitable
3463
3464 @item @emph{Return value}:
3465 Elapsed time in seconds since the last invocation or since the start of program
3466 execution if not called before.
3467
3468 @item @emph{Example}:
3469 @smallexample
3470 program test_dtime
3471     integer(8) :: i, j
3472     real, dimension(2) :: tarray
3473     real :: result
3474     call dtime(tarray, result)
3475     print *, result
3476     print *, tarray(1)
3477     print *, tarray(2)   
3478     do i=1,100000000    ! Just a delay
3479         j = i * i - i
3480     end do
3481     call dtime(tarray, result)
3482     print *, result
3483     print *, tarray(1)
3484     print *, tarray(2)
3485 end program test_dtime
3486 @end smallexample
3487
3488 @item @emph{See also}:
3489 @ref{CPU_TIME}
3490
3491 @end table
3492
3493
3494
3495 @node EOSHIFT
3496 @section @code{EOSHIFT} --- End-off shift elements of an array
3497 @fnindex EOSHIFT
3498 @cindex array, shift
3499
3500 @table @asis
3501 @item @emph{Description}:
3502 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3503 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3504 omitted it is taken to be @code{1}.  @var{DIM} is a scalar of type
3505 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3506 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3507 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3508 then all complete rank one sections of @var{ARRAY} along the given dimension are
3509 shifted.  Elements shifted out one end of each rank one section are dropped.  If
3510 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3511 is copied back in the other end.  If @var{BOUNDARY} is not present then the
3512 following are copied in depending on the type of @var{ARRAY}.
3513
3514 @multitable @columnfractions .15 .80
3515 @item @emph{Array Type} @tab @emph{Boundary Value}
3516 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3517 @item Logical  @tab @code{.FALSE.}.
3518 @item Character(@var{len}) @tab @var{len} blanks.
3519 @end multitable
3520
3521 @item @emph{Standard}:
3522 Fortran 95 and later
3523
3524 @item @emph{Class}:
3525 Transformational function
3526
3527 @item @emph{Syntax}:
3528 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3529
3530 @item @emph{Arguments}:
3531 @multitable @columnfractions .15 .70
3532 @item @var{ARRAY}  @tab May be any type, not scalar.
3533 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3534 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}. 
3535 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3536 @end multitable
3537
3538 @item @emph{Return value}:
3539 Returns an array of same type and rank as the @var{ARRAY} argument.
3540
3541 @item @emph{Example}:
3542 @smallexample
3543 program test_eoshift
3544     integer, dimension(3,3) :: a
3545     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3546     print '(3i3)', a(1,:)
3547     print '(3i3)', a(2,:)
3548     print '(3i3)', a(3,:)    
3549     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3550     print *
3551     print '(3i3)', a(1,:)
3552     print '(3i3)', a(2,:)
3553     print '(3i3)', a(3,:)
3554 end program test_eoshift
3555 @end smallexample
3556 @end table
3557
3558
3559
3560 @node EPSILON
3561 @section @code{EPSILON} --- Epsilon function
3562 @fnindex EPSILON
3563 @cindex model representation, epsilon
3564
3565 @table @asis
3566 @item @emph{Description}:
3567 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3568 as @var{X} such that @math{1 + E > 1}.
3569
3570 @item @emph{Standard}:
3571 Fortran 95 and later
3572
3573 @item @emph{Class}:
3574 Inquiry function
3575
3576 @item @emph{Syntax}:
3577 @code{RESULT = EPSILON(X)}
3578
3579 @item @emph{Arguments}:
3580 @multitable @columnfractions .15 .70
3581 @item @var{X} @tab The type shall be @code{REAL}.
3582 @end multitable
3583
3584 @item @emph{Return value}:
3585 The return value is of same type as the argument.
3586
3587 @item @emph{Example}:
3588 @smallexample
3589 program test_epsilon
3590     real :: x = 3.143
3591     real(8) :: y = 2.33
3592     print *, EPSILON(x)
3593     print *, EPSILON(y)
3594 end program test_epsilon
3595 @end smallexample
3596 @end table
3597
3598
3599
3600 @node ERF
3601 @section @code{ERF} --- Error function 
3602 @fnindex ERF
3603 @cindex error function
3604
3605 @table @asis
3606 @item @emph{Description}:
3607 @code{ERF(X)} computes the error function of @var{X}.
3608
3609 @item @emph{Standard}:
3610 Fortran 2008 and later
3611
3612 @item @emph{Class}:
3613 Elemental function
3614
3615 @item @emph{Syntax}:
3616 @code{RESULT = ERF(X)}
3617
3618 @item @emph{Arguments}:
3619 @multitable @columnfractions .15 .70
3620 @item @var{X} @tab The type shall be @code{REAL}.
3621 @end multitable
3622
3623 @item @emph{Return value}:
3624 The return value is of type @code{REAL}, of the same kind as
3625 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3626
3627 @item @emph{Example}:
3628 @smallexample
3629 program test_erf
3630   real(8) :: x = 0.17_8
3631   x = erf(x)
3632 end program test_erf
3633 @end smallexample
3634
3635 @item @emph{Specific names}:
3636 @multitable @columnfractions .20 .20 .20 .25
3637 @item Name            @tab Argument          @tab Return type       @tab Standard
3638 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3639 @end multitable
3640 @end table
3641
3642
3643
3644 @node ERFC
3645 @section @code{ERFC} --- Error function 
3646 @fnindex ERFC
3647 @cindex error function, complementary
3648
3649 @table @asis
3650 @item @emph{Description}:
3651 @code{ERFC(X)} computes the complementary error function of @var{X}.
3652
3653 @item @emph{Standard}:
3654 Fortran 2008 and later
3655
3656 @item @emph{Class}:
3657 Elemental function
3658
3659 @item @emph{Syntax}:
3660 @code{RESULT = ERFC(X)}
3661
3662 @item @emph{Arguments}:
3663 @multitable @columnfractions .15 .70
3664 @item @var{X} @tab The type shall be @code{REAL}.
3665 @end multitable
3666
3667 @item @emph{Return value}:
3668 The return value is of type @code{REAL} and of the same kind as @var{X}.
3669 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3670
3671 @item @emph{Example}:
3672 @smallexample
3673 program test_erfc
3674   real(8) :: x = 0.17_8
3675   x = erfc(x)
3676 end program test_erfc
3677 @end smallexample
3678
3679 @item @emph{Specific names}:
3680 @multitable @columnfractions .20 .20 .20 .25
3681 @item Name            @tab Argument          @tab Return type       @tab Standard
3682 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3683 @end multitable
3684 @end table
3685
3686
3687
3688 @node ERFC_SCALED
3689 @section @code{ERFC_SCALED} --- Error function 
3690 @fnindex ERFC_SCALED
3691 @cindex error function, complementary, exponentially-scaled
3692
3693 @table @asis
3694 @item @emph{Description}:
3695 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3696 error function of @var{X}.
3697
3698 @item @emph{Standard}:
3699 Fortran 2008 and later
3700
3701 @item @emph{Class}:
3702 Elemental function
3703
3704 @item @emph{Syntax}:
3705 @code{RESULT = ERFC_SCALED(X)}
3706
3707 @item @emph{Arguments}:
3708 @multitable @columnfractions .15 .70
3709 @item @var{X} @tab The type shall be @code{REAL}.
3710 @end multitable
3711
3712 @item @emph{Return value}:
3713 The return value is of type @code{REAL} and of the same kind as @var{X}.
3714
3715 @item @emph{Example}: