OSDN Git Service

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