OSDN Git Service

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