OSDN Git Service

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