OSDN Git Service

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