OSDN Git Service

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