OSDN Git Service

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