OSDN Git Service

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