OSDN Git Service

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