OSDN Git Service

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