OSDN Git Service

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