OSDN Git Service

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