OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-dev/] [or1k-gcc/] [gcc/] [fortran/] [intrinsic.texi] - Blame information for rev 712

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 712 jeremybenn
@ignore
2
Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2012
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{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
65
* @code{ATOMIC_REF}:    ATOMIC_REF, Obtaining the value of a variable atomically
66
* @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
67
* @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
68
* @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
69
* @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
70
* @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
71
* @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
72
* @code{BGE}:           BGE,       Bitwise greater than or equal to
73
* @code{BGT}:           BGT,       Bitwise greater than
74
* @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
75
* @code{BLE}:           BLE,       Bitwise less than or equal to
76
* @code{BLT}:           BLT,       Bitwise less than
77
* @code{BTEST}:         BTEST,     Bit test function
78
* @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
79
* @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
80
* @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
81
* @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
82
* @code{C_LOC}:         C_LOC,     Obtain the C address of an object
83
* @code{C_SIZEOF}:      C_SIZEOF,  Size in bytes of an expression
84
* @code{CEILING}:       CEILING,   Integer ceiling function
85
* @code{CHAR}:          CHAR,      Integer-to-character conversion function
86
* @code{CHDIR}:         CHDIR,     Change working directory
87
* @code{CHMOD}:         CHMOD,     Change access permissions of files
88
* @code{CMPLX}:         CMPLX,     Complex conversion function
89
* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
90
* @code{COMPLEX}:       COMPLEX,   Complex conversion function
91
* @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
92
* @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
93
* @code{CONJG}:         CONJG,     Complex conjugate function
94
* @code{COS}:           COS,       Cosine function
95
* @code{COSH}:          COSH,      Hyperbolic cosine function
96
* @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
97
* @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
98
* @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
99
* @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
100
* @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
101
* @code{DBLE}:          DBLE,      Double precision conversion function
102
* @code{DCMPLX}:        DCMPLX,    Double complex conversion function
103
* @code{DIGITS}:        DIGITS,    Significant digits function
104
* @code{DIM}:           DIM,       Positive difference
105
* @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
106
* @code{DPROD}:         DPROD,     Double product function
107
* @code{DREAL}:         DREAL,     Double real part function
108
* @code{DSHIFTL}:       DSHIFTL,   Combined left shift
109
* @code{DSHIFTR}:       DSHIFTR,   Combined right shift
110
* @code{DTIME}:         DTIME,     Execution time subroutine (or function)
111
* @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
112
* @code{EPSILON}:       EPSILON,   Epsilon function
113
* @code{ERF}:           ERF,       Error function
114
* @code{ERFC}:          ERFC,      Complementary error function
115
* @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
116
* @code{ETIME}:         ETIME,     Execution time subroutine (or function)
117
* @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
118
* @code{EXIT}:          EXIT,      Exit the program with status.
119
* @code{EXP}:           EXP,       Exponential function
120
* @code{EXPONENT}:      EXPONENT,  Exponent function
121
* @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF,  Query dynamic type for extension
122
* @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
123
* @code{FGET}:          FGET,      Read a single character in stream mode from stdin
124
* @code{FGETC}:         FGETC,     Read a single character in stream mode
125
* @code{FLOOR}:         FLOOR,     Integer floor function
126
* @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
127
* @code{FNUM}:          FNUM,      File number function
128
* @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
129
* @code{FPUTC}:         FPUTC,     Write a single character in stream mode
130
* @code{FRACTION}:      FRACTION,  Fractional part of the model representation
131
* @code{FREE}:          FREE,      Memory de-allocation subroutine
132
* @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
133
* @code{FSTAT}:         FSTAT,     Get file status
134
* @code{FTELL}:         FTELL,     Current stream position
135
* @code{GAMMA}:         GAMMA,     Gamma function
136
* @code{GERROR}:        GERROR,    Get last system error message
137
* @code{GETARG}:        GETARG,    Get command line arguments
138
* @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
139
* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
140
* @code{GETCWD}:        GETCWD,    Get current working directory
141
* @code{GETENV}:        GETENV,    Get an environmental variable
142
* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
143
* @code{GETGID}:        GETGID,    Group ID function
144
* @code{GETLOG}:        GETLOG,    Get login name
145
* @code{GETPID}:        GETPID,    Process ID function
146
* @code{GETUID}:        GETUID,    User ID function
147
* @code{GMTIME}:        GMTIME,    Convert time to GMT info
148
* @code{HOSTNM}:        HOSTNM,    Get system host name
149
* @code{HUGE}:          HUGE,      Largest number of a kind
150
* @code{HYPOT}:         HYPOT,     Euclidean distance function
151
* @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
152
* @code{IALL}:          IALL,      Bitwise AND of array elements
153
* @code{IAND}:          IAND,      Bitwise logical and
154
* @code{IANY}:          IANY,      Bitwise OR of array elements
155
* @code{IARGC}:         IARGC,     Get the number of command line arguments
156
* @code{IBCLR}:         IBCLR,     Clear bit
157
* @code{IBITS}:         IBITS,     Bit extraction
158
* @code{IBSET}:         IBSET,     Set bit
159
* @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
160
* @code{IDATE}:         IDATE,     Current local time (day/month/year)
161
* @code{IEOR}:          IEOR,      Bitwise logical exclusive or
162
* @code{IERRNO}:        IERRNO,    Function to get the last system error number
163
* @code{IMAGE_INDEX}:   IMAGE_INDEX, Cosubscript to image index conversion
164
* @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
165
* @code{INT}:           INT,       Convert to integer type
166
* @code{INT2}:          INT2,      Convert to 16-bit integer type
167
* @code{INT8}:          INT8,      Convert to 64-bit integer type
168
* @code{IOR}:           IOR,       Bitwise logical or
169
* @code{IPARITY}:       IPARITY,   Bitwise XOR of array elements
170
* @code{IRAND}:         IRAND,     Integer pseudo-random number
171
* @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
172
* @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
173
* @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
174
* @code{ISHFT}:         ISHFT,     Shift bits
175
* @code{ISHFTC}:        ISHFTC,    Shift bits circularly
176
* @code{ISNAN}:         ISNAN,     Tests for a NaN
177
* @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
178
* @code{KILL}:          KILL,      Send a signal to a process
179
* @code{KIND}:          KIND,      Kind of an entity
180
* @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
181
* @code{LCOBOUND}:      LCOBOUND,  Lower codimension bounds of an array
182
* @code{LEADZ}:         LEADZ,     Number of leading zero bits of an integer
183
* @code{LEN}:           LEN,       Length of a character entity
184
* @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
185
* @code{LGE}:           LGE,       Lexical greater than or equal
186
* @code{LGT}:           LGT,       Lexical greater than
187
* @code{LINK}:          LINK,      Create a hard link
188
* @code{LLE}:           LLE,       Lexical less than or equal
189
* @code{LLT}:           LLT,       Lexical less than
190
* @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
191
* @code{LOC}:           LOC,       Returns the address of a variable
192
* @code{LOG}:           LOG,       Logarithm function
193
* @code{LOG10}:         LOG10,     Base 10 logarithm function
194
* @code{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
195
* @code{LOGICAL}:       LOGICAL,   Convert to logical type
196
* @code{LONG}:          LONG,      Convert to integer type
197
* @code{LSHIFT}:        LSHIFT,    Left shift bits
198
* @code{LSTAT}:         LSTAT,     Get file status
199
* @code{LTIME}:         LTIME,     Convert time to local time info
200
* @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
201
* @code{MASKL}:         MASKL,     Left justified mask
202
* @code{MASKR}:         MASKR,     Right justified mask
203
* @code{MATMUL}:        MATMUL,    matrix multiplication
204
* @code{MAX}:           MAX,       Maximum value of an argument list
205
* @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
206
* @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
207
* @code{MAXVAL}:        MAXVAL,    Maximum value of an array
208
* @code{MCLOCK}:        MCLOCK,    Time function
209
* @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
210
* @code{MERGE}:         MERGE,     Merge arrays
211
* @code{MERGE_BITS}:    MERGE_BITS, Merge of bits under mask
212
* @code{MIN}:           MIN,       Minimum value of an argument list
213
* @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
214
* @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
215
* @code{MINVAL}:        MINVAL,    Minimum value of an array
216
* @code{MOD}:           MOD,       Remainder function
217
* @code{MODULO}:        MODULO,    Modulo function
218
* @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
219
* @code{MVBITS}:        MVBITS,    Move bits from one integer to another
220
* @code{NEAREST}:       NEAREST,   Nearest representable number
221
* @code{NEW_LINE}:      NEW_LINE,  New line character
222
* @code{NINT}:          NINT,      Nearest whole number
223
* @code{NORM2}:         NORM2,     Euclidean vector norm
224
* @code{NOT}:           NOT,       Logical negation
225
* @code{NULL}:          NULL,      Function that returns an disassociated pointer
226
* @code{NUM_IMAGES}:    NUM_IMAGES, Number of images
227
* @code{OR}:            OR,        Bitwise logical OR
228
* @code{PACK}:          PACK,      Pack an array into an array of rank one
229
* @code{PARITY}:        PARITY,    Reduction with exclusive OR
230
* @code{PERROR}:        PERROR,    Print system error message
231
* @code{POPCNT}:        POPCNT,    Number of bits set
232
* @code{POPPAR}:        POPPAR,    Parity of the number of bits set
233
* @code{PRECISION}:     PRECISION, Decimal precision of a real kind
234
* @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
235
* @code{PRODUCT}:       PRODUCT,   Product of array elements
236
* @code{RADIX}:         RADIX,     Base of a data model
237
* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
238
* @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
239
* @code{RAND}:          RAND,      Real pseudo-random number
240
* @code{RANGE}:         RANGE,     Decimal exponent range
241
* @code{RANK} :         RANK,      Rank of a data object
242
* @code{RAN}:           RAN,       Real pseudo-random number
243
* @code{REAL}:          REAL,      Convert to real type
244
* @code{RENAME}:        RENAME,    Rename a file
245
* @code{REPEAT}:        REPEAT,    Repeated string concatenation
246
* @code{RESHAPE}:       RESHAPE,   Function to reshape an array
247
* @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
248
* @code{RSHIFT}:        RSHIFT,    Right shift bits
249
* @code{SAME_TYPE_AS}:  SAME_TYPE_AS,  Query dynamic types for equality
250
* @code{SCALE}:         SCALE,     Scale a real value
251
* @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
252
* @code{SECNDS}:        SECNDS,    Time function
253
* @code{SECOND}:        SECOND,    CPU time function
254
* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
255
* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
256
* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
257
* @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
258
* @code{SHAPE}:         SHAPE,     Determine the shape of an array
259
* @code{SHIFTA}:        SHIFTA,    Right shift with fill
260
* @code{SHIFTL}:        SHIFTL,    Left shift
261
* @code{SHIFTR}:        SHIFTR,    Right shift
262
* @code{SIGN}:          SIGN,      Sign copying function
263
* @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
264
* @code{SIN}:           SIN,       Sine function
265
* @code{SINH}:          SINH,      Hyperbolic sine function
266
* @code{SIZE}:          SIZE,      Function to determine the size of an array
267
* @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
268
* @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
269
* @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
270
* @code{SPREAD}:        SPREAD,    Add a dimension to an array
271
* @code{SQRT}:          SQRT,      Square-root function
272
* @code{SRAND}:         SRAND,     Reinitialize the random number generator
273
* @code{STAT}:          STAT,      Get file status
274
* @code{STORAGE_SIZE}:  STORAGE_SIZE, Storage size in bits
275
* @code{SUM}:           SUM,       Sum of array elements
276
* @code{SYMLNK}:        SYMLNK,    Create a symbolic link
277
* @code{SYSTEM}:        SYSTEM,    Execute a shell command
278
* @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
279
* @code{TAN}:           TAN,       Tangent function
280
* @code{TANH}:          TANH,      Hyperbolic tangent function
281
* @code{THIS_IMAGE}:    THIS_IMAGE, Cosubscript index of this image
282
* @code{TIME}:          TIME,      Time function
283
* @code{TIME8}:         TIME8,     Time function (64-bit)
284
* @code{TINY}:          TINY,      Smallest positive number of a real kind
285
* @code{TRAILZ}:        TRAILZ,    Number of trailing zero bits of an integer
286
* @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
287
* @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
288
* @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
289
* @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
290
* @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
291
* @code{UCOBOUND}:      UCOBOUND,  Upper codimension bounds of an array
292
* @code{UMASK}:         UMASK,     Set the file creation mask
293
* @code{UNLINK}:        UNLINK,    Remove a file from the file system
294
* @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
295
* @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
296
* @code{XOR}:           XOR,       Bitwise logical exclusive or
297
@end menu
298
 
299
@node Introduction to Intrinsics
300
@section Introduction to intrinsic procedures
301
 
302
The intrinsic procedures provided by GNU Fortran include all of the
303
intrinsic procedures required by the Fortran 95 standard, a set of
304
intrinsic procedures for backwards compatibility with G77, and a
305
selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
306
standards.  Any conflict between a description here and a description in
307
either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
308
2008 standard is unintentional, and the standard(s) should be considered
309
authoritative.
310
 
311
The enumeration of the @code{KIND} type parameter is processor defined in
312
the Fortran 95 standard.  GNU Fortran defines the default integer type and
313
default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
314
respectively.  The standard mandates that both data types shall have
315
another kind, which have more precision.  On typical target architectures
316
supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
317
Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
318
In the description of generic intrinsic procedures, the kind type parameter
319
will be specified by @code{KIND=*}, and in the description of specific
320
names for an intrinsic procedure the kind type parameter will be explicitly
321
given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
322
brevity the optional @code{KIND=} syntax will be omitted.
323
 
324
Many of the intrinsic procedures take one or more optional arguments.
325
This document follows the convention used in the Fortran 95 standard,
326
and denotes such arguments by square brackets.
327
 
328
GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
329
which can be used to restrict the set of intrinsic procedures to a
330
given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
331
option, and so all intrinsic procedures described here are accepted.  There
332
is one caveat.  For a select group of intrinsic procedures, @command{g77}
333
implemented both a function and a subroutine.  Both classes
334
have been implemented in @command{gfortran} for backwards compatibility
335
with @command{g77}.  It is noted here that these functions and subroutines
336
cannot be intermixed in a given subprogram.  In the descriptions that follow,
337
the applicable standard for each intrinsic procedure is noted.
338
 
339
 
340
 
341
@node ABORT
342
@section @code{ABORT} --- Abort the program
343
@fnindex ABORT
344
@cindex program termination, with core dump
345
@cindex terminate program, with core dump
346
@cindex core, dump
347
 
348
@table @asis
349
@item @emph{Description}:
350
@code{ABORT} causes immediate termination of the program.  On operating
351
systems that support a core dump, @code{ABORT} will produce a core dump.
352
 
353
@item @emph{Standard}:
354
GNU extension
355
 
356
@item @emph{Class}:
357
Subroutine
358
 
359
@item @emph{Syntax}:
360
@code{CALL ABORT}
361
 
362
@item @emph{Return value}:
363
Does not return.
364
 
365
@item @emph{Example}:
366
@smallexample
367
program test_abort
368
  integer :: i = 1, j = 2
369
  if (i /= j) call abort
370
end program test_abort
371
@end smallexample
372
 
373
@item @emph{See also}:
374
@ref{EXIT}, @ref{KILL}
375
 
376
@end table
377
 
378
 
379
 
380
@node ABS
381
@section @code{ABS} --- Absolute value
382
@fnindex ABS
383
@fnindex CABS
384
@fnindex DABS
385
@fnindex IABS
386
@fnindex ZABS
387
@fnindex CDABS
388
@cindex absolute value
389
 
390
@table @asis
391
@item @emph{Description}:
392
@code{ABS(A)} computes the absolute value of @code{A}.
393
 
394
@item @emph{Standard}:
395
Fortran 77 and later, has overloads that are GNU extensions
396
 
397
@item @emph{Class}:
398
Elemental function
399
 
400
@item @emph{Syntax}:
401
@code{RESULT = ABS(A)}
402
 
403
@item @emph{Arguments}:
404
@multitable @columnfractions .15 .70
405
@item @var{A} @tab The type of the argument shall be an @code{INTEGER},
406
@code{REAL}, or @code{COMPLEX}.
407
@end multitable
408
 
409
@item @emph{Return value}:
410
The return value is of the same type and
411
kind as the argument except the return value is @code{REAL} for a
412
@code{COMPLEX} argument.
413
 
414
@item @emph{Example}:
415
@smallexample
416
program test_abs
417
  integer :: i = -1
418
  real :: x = -1.e0
419
  complex :: z = (-1.e0,0.e0)
420
  i = abs(i)
421
  x = abs(x)
422
  x = abs(z)
423
end program test_abs
424
@end smallexample
425
 
426
@item @emph{Specific names}:
427
@multitable @columnfractions .20 .20 .20 .25
428
@item Name            @tab Argument            @tab Return type       @tab Standard
429
@item @code{ABS(A)}   @tab @code{REAL(4) A}    @tab @code{REAL(4)}    @tab Fortran 77 and later
430
@item @code{CABS(A)}  @tab @code{COMPLEX(4) A} @tab @code{REAL(4)}    @tab Fortran 77 and later
431
@item @code{DABS(A)}  @tab @code{REAL(8) A}    @tab @code{REAL(8)}    @tab Fortran 77 and later
432
@item @code{IABS(A)}  @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
433
@item @code{ZABS(A)}  @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
434
@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
435
@end multitable
436
@end table
437
 
438
 
439
 
440
@node ACCESS
441
@section @code{ACCESS} --- Checks file access modes
442
@fnindex ACCESS
443
@cindex file system, access mode
444
 
445
@table @asis
446
@item @emph{Description}:
447
@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
448
exists, is readable, writable or executable. Except for the
449
executable check, @code{ACCESS} can be replaced by
450
Fortran 95's @code{INQUIRE}.
451
 
452
@item @emph{Standard}:
453
GNU extension
454
 
455
@item @emph{Class}:
456
Inquiry function
457
 
458
@item @emph{Syntax}:
459
@code{RESULT = ACCESS(NAME, MODE)}
460
 
461
@item @emph{Arguments}:
462
@multitable @columnfractions .15 .70
463
@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
464
file name. Tailing blank are ignored unless the character @code{achar(0)}
465
is present, then all characters up to and excluding @code{achar(0)} are
466
used as file name.
467
@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
468
file access mode, may be any concatenation of @code{"r"} (readable),
469
@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
470
for existence.
471
@end multitable
472
 
473
@item @emph{Return value}:
474
Returns a scalar @code{INTEGER}, which is @code{0} if the file is
475
accessible in the given mode; otherwise or if an invalid argument
476
has been given for @code{MODE} the value @code{1} is returned.
477
 
478
@item @emph{Example}:
479
@smallexample
480
program access_test
481
  implicit none
482
  character(len=*), parameter :: file  = 'test.dat'
483
  character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
484
  if(access(file,' ') == 0) print *, trim(file),' is exists'
485
  if(access(file,'r') == 0) print *, trim(file),' is readable'
486
  if(access(file,'w') == 0) print *, trim(file),' is writable'
487
  if(access(file,'x') == 0) print *, trim(file),' is executable'
488
  if(access(file2,'rwx') == 0) &
489
    print *, trim(file2),' is readable, writable and executable'
490
end program access_test
491
@end smallexample
492
@item @emph{Specific names}:
493
@item @emph{See also}:
494
 
495
@end table
496
 
497
 
498
 
499
@node ACHAR
500
@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
501
@fnindex ACHAR
502
@cindex @acronym{ASCII} collating sequence
503
@cindex collating sequence, @acronym{ASCII}
504
 
505
@table @asis
506
@item @emph{Description}:
507
@code{ACHAR(I)} returns the character located at position @code{I}
508
in the @acronym{ASCII} collating sequence.
509
 
510
@item @emph{Standard}:
511
Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
512
 
513
@item @emph{Class}:
514
Elemental function
515
 
516
@item @emph{Syntax}:
517
@code{RESULT = ACHAR(I [, KIND])}
518
 
519
@item @emph{Arguments}:
520
@multitable @columnfractions .15 .70
521
@item @var{I}    @tab The type shall be @code{INTEGER}.
522
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
523
expression indicating the kind parameter of the result.
524
@end multitable
525
 
526
@item @emph{Return value}:
527
The return value is of type @code{CHARACTER} with a length of one.
528
If the @var{KIND} argument is present, the return value is of the
529
specified kind and of the default kind otherwise.
530
 
531
@item @emph{Example}:
532
@smallexample
533
program test_achar
534
  character c
535
  c = achar(32)
536
end program test_achar
537
@end smallexample
538
 
539
@item @emph{Note}:
540
See @ref{ICHAR} for a discussion of converting between numerical values
541
and formatted string representations.
542
 
543
@item @emph{See also}:
544
@ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
545
 
546
@end table
547
 
548
 
549
 
550
@node ACOS
551
@section @code{ACOS} --- Arccosine function
552
@fnindex ACOS
553
@fnindex DACOS
554
@cindex trigonometric function, cosine, inverse
555
@cindex cosine, inverse
556
 
557
@table @asis
558
@item @emph{Description}:
559
@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
560
 
561
@item @emph{Standard}:
562
Fortran 77 and later, for a complex argument Fortran 2008 or later
563
 
564
@item @emph{Class}:
565
Elemental function
566
 
567
@item @emph{Syntax}:
568
@code{RESULT = ACOS(X)}
569
 
570
@item @emph{Arguments}:
571
@multitable @columnfractions .15 .70
572
@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
573
less than or equal to one - or the type shall be @code{COMPLEX}.
574
@end multitable
575
 
576
@item @emph{Return value}:
577
The return value is of the same type and kind as @var{X}.
578
The real part of the result is in radians and lies in the range
579
@math{0 \leq \Re \acos(x) \leq \pi}.
580
 
581
@item @emph{Example}:
582
@smallexample
583
program test_acos
584
  real(8) :: x = 0.866_8
585
  x = acos(x)
586
end program test_acos
587
@end smallexample
588
 
589
@item @emph{Specific names}:
590
@multitable @columnfractions .20 .20 .20 .25
591
@item Name            @tab Argument         @tab Return type     @tab Standard
592
@item @code{ACOS(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}  @tab Fortran 77 and later
593
@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}  @tab Fortran 77 and later
594
@end multitable
595
 
596
@item @emph{See also}:
597
Inverse function: @ref{COS}
598
 
599
@end table
600
 
601
 
602
 
603
@node ACOSH
604
@section @code{ACOSH} --- Inverse hyperbolic cosine function
605
@fnindex ACOSH
606
@fnindex DACOSH
607
@cindex area hyperbolic cosine
608
@cindex inverse hyperbolic cosine
609
@cindex hyperbolic function, cosine, inverse
610
@cindex cosine, hyperbolic, inverse
611
 
612
@table @asis
613
@item @emph{Description}:
614
@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
615
 
616
@item @emph{Standard}:
617
Fortran 2008 and later
618
 
619
@item @emph{Class}:
620
Elemental function
621
 
622
@item @emph{Syntax}:
623
@code{RESULT = ACOSH(X)}
624
 
625
@item @emph{Arguments}:
626
@multitable @columnfractions .15 .70
627
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
628
@end multitable
629
 
630
@item @emph{Return value}:
631
The return value has the same type and kind as @var{X}. If @var{X} is
632
complex, the imaginary part of the result is in radians and lies between
633
@math{ 0 \leq \Im \acosh(x) \leq \pi}.
634
 
635
@item @emph{Example}:
636
@smallexample
637
PROGRAM test_acosh
638
  REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
639
  WRITE (*,*) ACOSH(x)
640
END PROGRAM
641
@end smallexample
642
 
643
@item @emph{Specific names}:
644
@multitable @columnfractions .20 .20 .20 .25
645
@item Name             @tab Argument          @tab Return type       @tab Standard
646
@item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
647
@end multitable
648
 
649
@item @emph{See also}:
650
Inverse function: @ref{COSH}
651
@end table
652
 
653
 
654
 
655
@node ADJUSTL
656
@section @code{ADJUSTL} --- Left adjust a string
657
@fnindex ADJUSTL
658
@cindex string, adjust left
659
@cindex adjust string
660
 
661
@table @asis
662
@item @emph{Description}:
663
@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
664
Spaces are inserted at the end of the string as needed.
665
 
666
@item @emph{Standard}:
667
Fortran 90 and later
668
 
669
@item @emph{Class}:
670
Elemental function
671
 
672
@item @emph{Syntax}:
673
@code{RESULT = ADJUSTL(STRING)}
674
 
675
@item @emph{Arguments}:
676
@multitable @columnfractions .15 .70
677
@item @var{STRING} @tab The type shall be @code{CHARACTER}.
678
@end multitable
679
 
680
@item @emph{Return value}:
681
The return value is of type @code{CHARACTER} and of the same kind as
682
@var{STRING} where leading spaces are removed and the same number of
683
spaces are inserted on the end of @var{STRING}.
684
 
685
@item @emph{Example}:
686
@smallexample
687
program test_adjustl
688
  character(len=20) :: str = '   gfortran'
689
  str = adjustl(str)
690
  print *, str
691
end program test_adjustl
692
@end smallexample
693
 
694
@item @emph{See also}:
695
@ref{ADJUSTR}, @ref{TRIM}
696
@end table
697
 
698
 
699
 
700
@node ADJUSTR
701
@section @code{ADJUSTR} --- Right adjust a string
702
@fnindex ADJUSTR
703
@cindex string, adjust right
704
@cindex adjust string
705
 
706
@table @asis
707
@item @emph{Description}:
708
@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
709
Spaces are inserted at the start of the string as needed.
710
 
711
@item @emph{Standard}:
712
Fortran 95 and later
713
 
714
@item @emph{Class}:
715
Elemental function
716
 
717
@item @emph{Syntax}:
718
@code{RESULT = ADJUSTR(STRING)}
719
 
720
@item @emph{Arguments}:
721
@multitable @columnfractions .15 .70
722
@item @var{STR} @tab The type shall be @code{CHARACTER}.
723
@end multitable
724
 
725
@item @emph{Return value}:
726
The return value is of type @code{CHARACTER} and of the same kind as
727
@var{STRING} where trailing spaces are removed and the same number of
728
spaces are inserted at the start of @var{STRING}.
729
 
730
@item @emph{Example}:
731
@smallexample
732
program test_adjustr
733
  character(len=20) :: str = 'gfortran'
734
  str = adjustr(str)
735
  print *, str
736
end program test_adjustr
737
@end smallexample
738
 
739
@item @emph{See also}:
740
@ref{ADJUSTL}, @ref{TRIM}
741
@end table
742
 
743
 
744
 
745
@node AIMAG
746
@section @code{AIMAG} --- Imaginary part of complex number
747
@fnindex AIMAG
748
@fnindex DIMAG
749
@fnindex IMAG
750
@fnindex IMAGPART
751
@cindex complex numbers, imaginary part
752
 
753
@table @asis
754
@item @emph{Description}:
755
@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
756
The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
757
for compatibility with @command{g77}, and their use in new code is
758
strongly discouraged.
759
 
760
@item @emph{Standard}:
761
Fortran 77 and later, has overloads that are GNU extensions
762
 
763
@item @emph{Class}:
764
Elemental function
765
 
766
@item @emph{Syntax}:
767
@code{RESULT = AIMAG(Z)}
768
 
769
@item @emph{Arguments}:
770
@multitable @columnfractions .15 .70
771
@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
772
@end multitable
773
 
774
@item @emph{Return value}:
775
The return value is of type @code{REAL} with the
776
kind type parameter of the argument.
777
 
778
@item @emph{Example}:
779
@smallexample
780
program test_aimag
781
  complex(4) z4
782
  complex(8) z8
783
  z4 = cmplx(1.e0_4, 0.e0_4)
784
  z8 = cmplx(0.e0_8, 1.e0_8)
785
  print *, aimag(z4), dimag(z8)
786
end program test_aimag
787
@end smallexample
788
 
789
@item @emph{Specific names}:
790
@multitable @columnfractions .20 .20 .20 .25
791
@item Name               @tab Argument            @tab Return type     @tab Standard
792
@item @code{AIMAG(Z)}    @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
793
@item @code{DIMAG(Z)}    @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}  @tab GNU extension
794
@item @code{IMAG(Z)}     @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
795
@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
796
@end multitable
797
@end table
798
 
799
 
800
 
801
@node AINT
802
@section @code{AINT} --- Truncate to a whole number
803
@fnindex AINT
804
@fnindex DINT
805
@cindex floor
806
@cindex rounding, floor
807
 
808
@table @asis
809
@item @emph{Description}:
810
@code{AINT(A [, KIND])} truncates its argument to a whole number.
811
 
812
@item @emph{Standard}:
813
Fortran 77 and later
814
 
815
@item @emph{Class}:
816
Elemental function
817
 
818
@item @emph{Syntax}:
819
@code{RESULT = AINT(A [, KIND])}
820
 
821
@item @emph{Arguments}:
822
@multitable @columnfractions .15 .70
823
@item @var{A}    @tab The type of the argument shall be @code{REAL}.
824
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
825
expression indicating the kind parameter of the result.
826
@end multitable
827
 
828
@item @emph{Return value}:
829
The return value is of type @code{REAL} with the kind type parameter of the
830
argument if the optional @var{KIND} is absent; otherwise, the kind
831
type parameter will be given by @var{KIND}.  If the magnitude of
832
@var{X} is less than one, @code{AINT(X)} returns zero.  If the
833
magnitude is equal to or greater than one then it returns the largest
834
whole number that does not exceed its magnitude.  The sign is the same
835
as the sign of @var{X}.
836
 
837
@item @emph{Example}:
838
@smallexample
839
program test_aint
840
  real(4) x4
841
  real(8) x8
842
  x4 = 1.234E0_4
843
  x8 = 4.321_8
844
  print *, aint(x4), dint(x8)
845
  x8 = aint(x4,8)
846
end program test_aint
847
@end smallexample
848
 
849
@item @emph{Specific names}:
850
@multitable @columnfractions .20 .20 .20 .25
851
@item Name           @tab Argument         @tab Return type      @tab Standard
852
@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
853
@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
854
@end multitable
855
@end table
856
 
857
 
858
 
859
@node ALARM
860
@section @code{ALARM} --- Execute a routine after a given delay
861
@fnindex ALARM
862
@cindex delayed execution
863
 
864
@table @asis
865
@item @emph{Description}:
866
@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
867
to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
868
set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
869
supplied, it will be returned with the number of seconds remaining until
870
any previously scheduled alarm was due to be delivered, or zero if there
871
was no previously scheduled alarm.
872
 
873
@item @emph{Standard}:
874
GNU extension
875
 
876
@item @emph{Class}:
877
Subroutine
878
 
879
@item @emph{Syntax}:
880
@code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
881
 
882
@item @emph{Arguments}:
883
@multitable @columnfractions .15 .70
884
@item @var{SECONDS} @tab The type of the argument shall be a scalar
885
@code{INTEGER}. It is @code{INTENT(IN)}.
886
@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
887
@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
888
values may be either @code{SIG_IGN=1} to ignore the alarm generated
889
or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
890
@item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
891
variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
892
@end multitable
893
 
894
@item @emph{Example}:
895
@smallexample
896
program test_alarm
897
  external handler_print
898
  integer i
899
  call alarm (3, handler_print, i)
900
  print *, i
901
  call sleep(10)
902
end program test_alarm
903
@end smallexample
904
This will cause the external routine @var{handler_print} to be called
905
after 3 seconds.
906
@end table
907
 
908
 
909
 
910
@node ALL
911
@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
912
@fnindex ALL
913
@cindex array, apply condition
914
@cindex array, condition testing
915
 
916
@table @asis
917
@item @emph{Description}:
918
@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
919
in the array along dimension @var{DIM}.
920
 
921
@item @emph{Standard}:
922
Fortran 95 and later
923
 
924
@item @emph{Class}:
925
Transformational function
926
 
927
@item @emph{Syntax}:
928
@code{RESULT = ALL(MASK [, DIM])}
929
 
930
@item @emph{Arguments}:
931
@multitable @columnfractions .15 .70
932
@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
933
it shall not be scalar.
934
@item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
935
with a value that lies between one and the rank of @var{MASK}.
936
@end multitable
937
 
938
@item @emph{Return value}:
939
@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
940
the kind type parameter is the same as the kind type parameter of
941
@var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
942
an array with the rank of @var{MASK} minus 1.  The shape is determined from
943
the shape of @var{MASK} where the @var{DIM} dimension is elided.
944
 
945
@table @asis
946
@item (A)
947
@code{ALL(MASK)} is true if all elements of @var{MASK} are true.
948
It also is true if @var{MASK} has zero size; otherwise, it is false.
949
@item (B)
950
If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
951
to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
952
is determined by applying @code{ALL} to the array sections.
953
@end table
954
 
955
@item @emph{Example}:
956
@smallexample
957
program test_all
958
  logical l
959
  l = all((/.true., .true., .true./))
960
  print *, l
961
  call section
962
  contains
963
    subroutine section
964
      integer a(2,3), b(2,3)
965
      a = 1
966
      b = 1
967
      b(2,2) = 2
968
      print *, all(a .eq. b, 1)
969
      print *, all(a .eq. b, 2)
970
    end subroutine section
971
end program test_all
972
@end smallexample
973
@end table
974
 
975
 
976
 
977
@node ALLOCATED
978
@section @code{ALLOCATED} --- Status of an allocatable entity
979
@fnindex ALLOCATED
980
@cindex allocation, status
981
 
982
@table @asis
983
@item @emph{Description}:
984
@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
985
status of @var{ARRAY} and @var{SCALAR}, respectively.
986
 
987
@item @emph{Standard}:
988
Fortran 95 and later.  Note, the @code{SCALAR=} keyword and allocatable
989
scalar entities are available in Fortran 2003 and later.
990
 
991
@item @emph{Class}:
992
Inquiry function
993
 
994
@item @emph{Syntax}:
995
@multitable @columnfractions .80
996
@item @code{RESULT = ALLOCATED(ARRAY)}
997
@item @code{RESULT = ALLOCATED(SCALAR)}
998
@end multitable
999
 
1000
@item @emph{Arguments}:
1001
@multitable @columnfractions .15 .70
1002
@item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
1003
@item @var{SCALAR}   @tab The argument shall be an @code{ALLOCATABLE} scalar.
1004
@end multitable
1005
 
1006
@item @emph{Return value}:
1007
The return value is a scalar @code{LOGICAL} with the default logical
1008
kind type parameter.  If the argument is allocated, then the result is
1009
@code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1010
 
1011
@item @emph{Example}:
1012
@smallexample
1013
program test_allocated
1014
  integer :: i = 4
1015
  real(4), allocatable :: x(:)
1016
  if (.not. allocated(x)) allocate(x(i))
1017
end program test_allocated
1018
@end smallexample
1019
@end table
1020
 
1021
 
1022
 
1023
@node AND
1024
@section @code{AND} --- Bitwise logical AND
1025
@fnindex AND
1026
@cindex bitwise logical and
1027
@cindex logical and, bitwise
1028
 
1029
@table @asis
1030
@item @emph{Description}:
1031
Bitwise logical @code{AND}.
1032
 
1033
This intrinsic routine is provided for backwards compatibility with
1034
GNU Fortran 77.  For integer arguments, programmers should consider
1035
the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1036
 
1037
@item @emph{Standard}:
1038
GNU extension
1039
 
1040
@item @emph{Class}:
1041
Function
1042
 
1043
@item @emph{Syntax}:
1044
@code{RESULT = AND(I, J)}
1045
 
1046
@item @emph{Arguments}:
1047
@multitable @columnfractions .15 .70
1048
@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1049
type or a scalar @code{LOGICAL} type.
1050
@item @var{J} @tab The type shall be the same as the type of @var{I}.
1051
@end multitable
1052
 
1053
@item @emph{Return value}:
1054
The return type is either a scalar @code{INTEGER} or a scalar
1055
@code{LOGICAL}.  If the kind type parameters differ, then the
1056
smaller kind type is implicitly converted to larger kind, and the
1057
return has the larger kind.
1058
 
1059
@item @emph{Example}:
1060
@smallexample
1061
PROGRAM test_and
1062
  LOGICAL :: T = .TRUE., F = .FALSE.
1063
  INTEGER :: a, b
1064
  DATA a / Z'F' /, b / Z'3' /
1065
 
1066
  WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1067
  WRITE (*,*) AND(a, b)
1068
END PROGRAM
1069
@end smallexample
1070
 
1071
@item @emph{See also}:
1072
Fortran 95 elemental function: @ref{IAND}
1073
@end table
1074
 
1075
 
1076
 
1077
@node ANINT
1078
@section @code{ANINT} --- Nearest whole number
1079
@fnindex ANINT
1080
@fnindex DNINT
1081
@cindex ceiling
1082
@cindex rounding, ceiling
1083
 
1084
@table @asis
1085
@item @emph{Description}:
1086
@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1087
 
1088
@item @emph{Standard}:
1089
Fortran 77 and later
1090
 
1091
@item @emph{Class}:
1092
Elemental function
1093
 
1094
@item @emph{Syntax}:
1095
@code{RESULT = ANINT(A [, KIND])}
1096
 
1097
@item @emph{Arguments}:
1098
@multitable @columnfractions .15 .70
1099
@item @var{A}    @tab The type of the argument shall be @code{REAL}.
1100
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1101
expression indicating the kind parameter of the result.
1102
@end multitable
1103
 
1104
@item @emph{Return value}:
1105
The return value is of type real with the kind type parameter of the
1106
argument if the optional @var{KIND} is absent; otherwise, the kind
1107
type parameter will be given by @var{KIND}.  If @var{A} is greater than
1108
zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
1109
less than or equal to zero then it returns @code{AINT(X-0.5)}.
1110
 
1111
@item @emph{Example}:
1112
@smallexample
1113
program test_anint
1114
  real(4) x4
1115
  real(8) x8
1116
  x4 = 1.234E0_4
1117
  x8 = 4.321_8
1118
  print *, anint(x4), dnint(x8)
1119
  x8 = anint(x4,8)
1120
end program test_anint
1121
@end smallexample
1122
 
1123
@item @emph{Specific names}:
1124
@multitable @columnfractions .20 .20 .20 .25
1125
@item Name            @tab Argument         @tab Return type      @tab Standard
1126
@item @code{AINT(A)}  @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
1127
@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
1128
@end multitable
1129
@end table
1130
 
1131
 
1132
 
1133
@node ANY
1134
@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1135
@fnindex ANY
1136
@cindex array, apply condition
1137
@cindex array, condition testing
1138
 
1139
@table @asis
1140
@item @emph{Description}:
1141
@code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1142
@var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1143
 
1144
@item @emph{Standard}:
1145
Fortran 95 and later
1146
 
1147
@item @emph{Class}:
1148
Transformational function
1149
 
1150
@item @emph{Syntax}:
1151
@code{RESULT = ANY(MASK [, DIM])}
1152
 
1153
@item @emph{Arguments}:
1154
@multitable @columnfractions .15 .70
1155
@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1156
it shall not be scalar.
1157
@item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1158
with a value that lies between one and the rank of @var{MASK}.
1159
@end multitable
1160
 
1161
@item @emph{Return value}:
1162
@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1163
the kind type parameter is the same as the kind type parameter of
1164
@var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1165
an array with the rank of @var{MASK} minus 1.  The shape is determined from
1166
the shape of @var{MASK} where the @var{DIM} dimension is elided.
1167
 
1168
@table @asis
1169
@item (A)
1170
@code{ANY(MASK)} is true if any element of @var{MASK} is true;
1171
otherwise, it is false.  It also is false if @var{MASK} has zero size.
1172
@item (B)
1173
If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1174
to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1175
is determined by applying @code{ANY} to the array sections.
1176
@end table
1177
 
1178
@item @emph{Example}:
1179
@smallexample
1180
program test_any
1181
  logical l
1182
  l = any((/.true., .true., .true./))
1183
  print *, l
1184
  call section
1185
  contains
1186
    subroutine section
1187
      integer a(2,3), b(2,3)
1188
      a = 1
1189
      b = 1
1190
      b(2,2) = 2
1191
      print *, any(a .eq. b, 1)
1192
      print *, any(a .eq. b, 2)
1193
    end subroutine section
1194
end program test_any
1195
@end smallexample
1196
@end table
1197
 
1198
 
1199
 
1200
@node ASIN
1201
@section @code{ASIN} --- Arcsine function
1202
@fnindex ASIN
1203
@fnindex DASIN
1204
@cindex trigonometric function, sine, inverse
1205
@cindex sine, inverse
1206
 
1207
@table @asis
1208
@item @emph{Description}:
1209
@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1210
 
1211
@item @emph{Standard}:
1212
Fortran 77 and later, for a complex argument Fortran 2008 or later
1213
 
1214
@item @emph{Class}:
1215
Elemental function
1216
 
1217
@item @emph{Syntax}:
1218
@code{RESULT = ASIN(X)}
1219
 
1220
@item @emph{Arguments}:
1221
@multitable @columnfractions .15 .70
1222
@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1223
less than or equal to one - or be @code{COMPLEX}.
1224
@end multitable
1225
 
1226
@item @emph{Return value}:
1227
The return value is of the same type and kind as @var{X}.
1228
The real part of the result is in radians and lies in the range
1229
@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1230
 
1231
@item @emph{Example}:
1232
@smallexample
1233
program test_asin
1234
  real(8) :: x = 0.866_8
1235
  x = asin(x)
1236
end program test_asin
1237
@end smallexample
1238
 
1239
@item @emph{Specific names}:
1240
@multitable @columnfractions .20 .20 .20 .25
1241
@item Name            @tab Argument          @tab Return type       @tab Standard
1242
@item @code{ASIN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1243
@item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1244
@end multitable
1245
 
1246
@item @emph{See also}:
1247
Inverse function: @ref{SIN}
1248
 
1249
@end table
1250
 
1251
 
1252
 
1253
@node ASINH
1254
@section @code{ASINH} --- Inverse hyperbolic sine function
1255
@fnindex ASINH
1256
@fnindex DASINH
1257
@cindex area hyperbolic sine
1258
@cindex inverse hyperbolic sine
1259
@cindex hyperbolic function, sine, inverse
1260
@cindex sine, hyperbolic, inverse
1261
 
1262
@table @asis
1263
@item @emph{Description}:
1264
@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1265
 
1266
@item @emph{Standard}:
1267
Fortran 2008 and later
1268
 
1269
@item @emph{Class}:
1270
Elemental function
1271
 
1272
@item @emph{Syntax}:
1273
@code{RESULT = ASINH(X)}
1274
 
1275
@item @emph{Arguments}:
1276
@multitable @columnfractions .15 .70
1277
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1278
@end multitable
1279
 
1280
@item @emph{Return value}:
1281
The return value is of the same type and kind as  @var{X}. If @var{X} is
1282
complex, the imaginary part of the result is in radians and lies between
1283
@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1284
 
1285
@item @emph{Example}:
1286
@smallexample
1287
PROGRAM test_asinh
1288
  REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1289
  WRITE (*,*) ASINH(x)
1290
END PROGRAM
1291
@end smallexample
1292
 
1293
@item @emph{Specific names}:
1294
@multitable @columnfractions .20 .20 .20 .25
1295
@item Name             @tab Argument          @tab Return type       @tab Standard
1296
@item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1297
@end multitable
1298
 
1299
@item @emph{See also}:
1300
Inverse function: @ref{SINH}
1301
@end table
1302
 
1303
 
1304
 
1305
@node ASSOCIATED
1306
@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1307
@fnindex ASSOCIATED
1308
@cindex pointer, status
1309
@cindex association status
1310
 
1311
@table @asis
1312
@item @emph{Description}:
1313
@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1314
@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1315
 
1316
@item @emph{Standard}:
1317
Fortran 95 and later
1318
 
1319
@item @emph{Class}:
1320
Inquiry function
1321
 
1322
@item @emph{Syntax}:
1323
@code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1324
 
1325
@item @emph{Arguments}:
1326
@multitable @columnfractions .15 .70
1327
@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1328
and it can be of any type.
1329
@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1330
a target.  It must have the same type, kind type parameter, and
1331
array rank as @var{POINTER}.
1332
@end multitable
1333
The association status of neither @var{POINTER} nor @var{TARGET} shall be
1334
undefined.
1335
 
1336
@item @emph{Return value}:
1337
@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1338
There are several cases:
1339
@table @asis
1340
@item (A) When the optional @var{TARGET} is not present then
1341
@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1342
@item (B) If @var{TARGET} is present and a scalar target, the result is true if
1343
@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
1344
disassociated, the result is false.
1345
@item (C) If @var{TARGET} is present and an array target, the result is true if
1346
@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1347
are arrays whose elements are not zero-sized storage sequences, and
1348
@var{TARGET} and @var{POINTER} occupy the same storage units in array element
1349
order.
1350
As in case(B), the result is false, if @var{POINTER} is disassociated.
1351
@item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1352
if @var{TARGET} is associated with @var{POINTER}, the target associated with
1353
@var{TARGET} are not zero-sized storage sequences and occupy the same storage
1354
units.
1355
The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1356
@item (E) If @var{TARGET} is present and an array pointer, the result is true if
1357
target associated with @var{POINTER} and the target associated with @var{TARGET}
1358
have the same shape, are not zero-sized arrays, are arrays whose elements are
1359
not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1360
the same storage units in array element order.
1361
The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1362
@end table
1363
 
1364
@item @emph{Example}:
1365
@smallexample
1366
program test_associated
1367
   implicit none
1368
   real, target  :: tgt(2) = (/1., 2./)
1369
   real, pointer :: ptr(:)
1370
   ptr => tgt
1371
   if (associated(ptr)     .eqv. .false.) call abort
1372
   if (associated(ptr,tgt) .eqv. .false.) call abort
1373
end program test_associated
1374
@end smallexample
1375
 
1376
@item @emph{See also}:
1377
@ref{NULL}
1378
@end table
1379
 
1380
 
1381
 
1382
@node ATAN
1383
@section @code{ATAN} --- Arctangent function
1384
@fnindex ATAN
1385
@fnindex DATAN
1386
@cindex trigonometric function, tangent, inverse
1387
@cindex tangent, inverse
1388
 
1389
@table @asis
1390
@item @emph{Description}:
1391
@code{ATAN(X)} computes the arctangent of @var{X}.
1392
 
1393
@item @emph{Standard}:
1394
Fortran 77 and later, for a complex argument and for two arguments
1395
Fortran 2008 or later
1396
 
1397
@item @emph{Class}:
1398
Elemental function
1399
 
1400
@item @emph{Syntax}:
1401
@multitable @columnfractions .80
1402
@item @code{RESULT = ATAN(X)}
1403
@item @code{RESULT = ATAN(Y, X)}
1404
@end multitable
1405
 
1406
@item @emph{Arguments}:
1407
@multitable @columnfractions .15 .70
1408
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1409
if @var{Y} is present, @var{X} shall be REAL.
1410
@item @var{Y} shall be of the same type and kind as @var{X}.
1411
@end multitable
1412
 
1413
@item @emph{Return value}:
1414
The return value is of the same type and kind as @var{X}.
1415
If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1416
Otherwise, it the arcus tangent of @var{X}, where the real part of
1417
the result is in radians and lies in the range
1418
@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1419
 
1420
@item @emph{Example}:
1421
@smallexample
1422
program test_atan
1423
  real(8) :: x = 2.866_8
1424
  x = atan(x)
1425
end program test_atan
1426
@end smallexample
1427
 
1428
@item @emph{Specific names}:
1429
@multitable @columnfractions .20 .20 .20 .25
1430
@item Name            @tab Argument          @tab Return type       @tab Standard
1431
@item @code{ATAN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1432
@item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1433
@end multitable
1434
 
1435
@item @emph{See also}:
1436
Inverse function: @ref{TAN}
1437
 
1438
@end table
1439
 
1440
 
1441
 
1442
@node ATAN2
1443
@section @code{ATAN2} --- Arctangent function
1444
@fnindex ATAN2
1445
@fnindex DATAN2
1446
@cindex trigonometric function, tangent, inverse
1447
@cindex tangent, inverse
1448
 
1449
@table @asis
1450
@item @emph{Description}:
1451
@code{ATAN2(Y, X)} computes the principal value of the argument
1452
function of the complex number @math{X + i Y}. This function can
1453
be used to transform from Cartesian into polar coordinates and
1454
allows to determine the angle in the correct quadrant.
1455
 
1456
@item @emph{Standard}:
1457
Fortran 77 and later
1458
 
1459
@item @emph{Class}:
1460
Elemental function
1461
 
1462
@item @emph{Syntax}:
1463
@code{RESULT = ATAN2(Y, X)}
1464
 
1465
@item @emph{Arguments}:
1466
@multitable @columnfractions .15 .70
1467
@item @var{Y} @tab The type shall be @code{REAL}.
1468
@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1469
If @var{Y} is zero, then @var{X} must be nonzero.
1470
@end multitable
1471
 
1472
@item @emph{Return value}:
1473
The return value has the same type and kind type parameter as @var{Y}. It
1474
is the principal value of the complex number @math{X + i Y}.  If @var{X}
1475
is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1476
The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1477
the return value is zero if @var{X} is strictly positive, @math{\pi} if
1478
@var{X} is negative and @var{Y} is positive zero (or the processor does
1479
not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1480
@var{Y} is negative zero.  Finally, if @var{X} is zero, then the
1481
magnitude of the result is @math{\pi/2}.
1482
 
1483
@item @emph{Example}:
1484
@smallexample
1485
program test_atan2
1486
  real(4) :: x = 1.e0_4, y = 0.5e0_4
1487
  x = atan2(y,x)
1488
end program test_atan2
1489
@end smallexample
1490
 
1491
@item @emph{Specific names}:
1492
@multitable @columnfractions .20 .20 .20 .25
1493
@item Name                @tab Argument            @tab Return type    @tab Standard
1494
@item @code{ATAN2(X, Y)}  @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1495
@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1496
@end multitable
1497
@end table
1498
 
1499
 
1500
 
1501
@node ATANH
1502
@section @code{ATANH} --- Inverse hyperbolic tangent function
1503
@fnindex ATANH
1504
@fnindex DATANH
1505
@cindex area hyperbolic tangent
1506
@cindex inverse hyperbolic tangent
1507
@cindex hyperbolic function, tangent, inverse
1508
@cindex tangent, hyperbolic, inverse
1509
 
1510
@table @asis
1511
@item @emph{Description}:
1512
@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1513
 
1514
@item @emph{Standard}:
1515
Fortran 2008 and later
1516
 
1517
@item @emph{Class}:
1518
Elemental function
1519
 
1520
@item @emph{Syntax}:
1521
@code{RESULT = ATANH(X)}
1522
 
1523
@item @emph{Arguments}:
1524
@multitable @columnfractions .15 .70
1525
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1526
@end multitable
1527
 
1528
@item @emph{Return value}:
1529
The return value has same type and kind as @var{X}. If @var{X} is
1530
complex, the imaginary part of the result is in radians and lies between
1531
@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1532
 
1533
@item @emph{Example}:
1534
@smallexample
1535
PROGRAM test_atanh
1536
  REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1537
  WRITE (*,*) ATANH(x)
1538
END PROGRAM
1539
@end smallexample
1540
 
1541
@item @emph{Specific names}:
1542
@multitable @columnfractions .20 .20 .20 .25
1543
@item Name             @tab Argument          @tab Return type       @tab Standard
1544
@item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1545
@end multitable
1546
 
1547
@item @emph{See also}:
1548
Inverse function: @ref{TANH}
1549
@end table
1550
 
1551
 
1552
 
1553
@node ATOMIC_DEFINE
1554
@section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1555
@fnindex ATOMIC_DEFINE
1556
@cindex Atomic subroutine, define
1557
 
1558
@table @asis
1559
@item @emph{Description}:
1560
@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1561
@var{VALUE} atomically.
1562
 
1563
@item @emph{Standard}:
1564
Fortran 2008 and later
1565
 
1566
@item @emph{Class}:
1567
Atomic subroutine
1568
 
1569
@item @emph{Syntax}:
1570
@code{CALL ATOMIC_DEFINE(ATOM, VALUE)}
1571
 
1572
@item @emph{Arguments}:
1573
@multitable @columnfractions .15 .70
1574
@item @var{ATOM}   @tab Scalar coarray or coindexed variable of either integer
1575
                        type with @code{ATOMIC_INT_KIND} kind or logical type
1576
                        with @code{ATOMIC_LOGICAL_KIND} kind.
1577
@item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1578
                        is different, the value is converted to the kind of
1579
                        @var{ATOM}.
1580
@end multitable
1581
 
1582
@item @emph{Example}:
1583
@smallexample
1584
program atomic
1585
  use iso_fortran_env
1586
  integer(atomic_int_kind) :: atom[*]
1587
  call atomic_define (atom[1], this_image())
1588
end program atomic
1589
@end smallexample
1590
 
1591
@item @emph{See also}:
1592
@ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1593
@end table
1594
 
1595
 
1596
 
1597
@node ATOMIC_REF
1598
@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
1599
@fnindex ATOMIC_REF
1600
@cindex Atomic subroutine, reference
1601
 
1602
@table @asis
1603
@item @emph{Description}:
1604
@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
1605
variable @var{ATOM} to @var{VALUE}.
1606
 
1607
@item @emph{Standard}:
1608
Fortran 2008 and later
1609
 
1610
@item @emph{Class}:
1611
Atomic subroutine
1612
 
1613
@item @emph{Syntax}:
1614
@code{CALL ATOMIC_REF(VALUE, ATOM)}
1615
 
1616
@item @emph{Arguments}:
1617
@multitable @columnfractions .15 .70
1618
@item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1619
                        is different, the value is converted to the kind of
1620
                        @var{ATOM}.
1621
@item @var{ATOM}   @tab Scalar coarray or coindexed variable of either integer
1622
                        type with @code{ATOMIC_INT_KIND} kind or logical type
1623
                        with @code{ATOMIC_LOGICAL_KIND} kind.
1624
@end multitable
1625
 
1626
@item @emph{Example}:
1627
@smallexample
1628
program atomic
1629
  use iso_fortran_env
1630
  logical(atomic_logical_kind) :: atom[*]
1631
  logical :: val
1632
  call atomic_ref (atom, .false.)
1633
  ! ...
1634
  call atomic_ref (atom, val)
1635
  if (val) then
1636
    print *, "Obtained"
1637
  end if
1638
end program atomic
1639
@end smallexample
1640
 
1641
@item @emph{See also}:
1642
@ref{ATOMIC_DEFINE}, @ref{ISO_FORTRAN_ENV}
1643
@end table
1644
 
1645
 
1646
 
1647
@node BESSEL_J0
1648
@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1649
@fnindex BESSEL_J0
1650
@fnindex BESJ0
1651
@fnindex DBESJ0
1652
@cindex Bessel function, first kind
1653
 
1654
@table @asis
1655
@item @emph{Description}:
1656
@code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1657
order 0 of @var{X}. This function is available under the name
1658
@code{BESJ0} as a GNU extension.
1659
 
1660
@item @emph{Standard}:
1661
Fortran 2008 and later
1662
 
1663
@item @emph{Class}:
1664
Elemental function
1665
 
1666
@item @emph{Syntax}:
1667
@code{RESULT = BESSEL_J0(X)}
1668
 
1669
@item @emph{Arguments}:
1670
@multitable @columnfractions .15 .70
1671
@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1672
@end multitable
1673
 
1674
@item @emph{Return value}:
1675
The return value is of type @code{REAL} and lies in the
1676
range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1677
kind as @var{X}.
1678
 
1679
@item @emph{Example}:
1680
@smallexample
1681
program test_besj0
1682
  real(8) :: x = 0.0_8
1683
  x = bessel_j0(x)
1684
end program test_besj0
1685
@end smallexample
1686
 
1687
@item @emph{Specific names}:
1688
@multitable @columnfractions .20 .20 .20 .25
1689
@item Name            @tab Argument          @tab Return type       @tab Standard
1690
@item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1691
@end multitable
1692
@end table
1693
 
1694
 
1695
 
1696
@node BESSEL_J1
1697
@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1698
@fnindex BESSEL_J1
1699
@fnindex BESJ1
1700
@fnindex DBESJ1
1701
@cindex Bessel function, first kind
1702
 
1703
@table @asis
1704
@item @emph{Description}:
1705
@code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1706
order 1 of @var{X}. This function is available under the name
1707
@code{BESJ1} as a GNU extension.
1708
 
1709
@item @emph{Standard}:
1710
Fortran 2008
1711
 
1712
@item @emph{Class}:
1713
Elemental function
1714
 
1715
@item @emph{Syntax}:
1716
@code{RESULT = BESSEL_J1(X)}
1717
 
1718
@item @emph{Arguments}:
1719
@multitable @columnfractions .15 .70
1720
@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1721
@end multitable
1722
 
1723
@item @emph{Return value}:
1724
The return value is of type @code{REAL} and it lies in the
1725
range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1726
kind as @var{X}.
1727
 
1728
@item @emph{Example}:
1729
@smallexample
1730
program test_besj1
1731
  real(8) :: x = 1.0_8
1732
  x = bessel_j1(x)
1733
end program test_besj1
1734
@end smallexample
1735
 
1736
@item @emph{Specific names}:
1737
@multitable @columnfractions .20 .20 .20 .25
1738
@item Name             @tab Argument          @tab Return type       @tab Standard
1739
@item @code{DBESJ1(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1740
@end multitable
1741
@end table
1742
 
1743
 
1744
 
1745
@node BESSEL_JN
1746
@section @code{BESSEL_JN} --- Bessel function of the first kind
1747
@fnindex BESSEL_JN
1748
@fnindex BESJN
1749
@fnindex DBESJN
1750
@cindex Bessel function, first kind
1751
 
1752
@table @asis
1753
@item @emph{Description}:
1754
@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1755
order @var{N} of @var{X}. This function is available under the name
1756
@code{BESJN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1757
their ranks and shapes shall conform.
1758
 
1759
@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1760
of the first kind of the orders @var{N1} to @var{N2}.
1761
 
1762
@item @emph{Standard}:
1763
Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1764
 
1765
@item @emph{Class}:
1766
Elemental function, except for the transformational function
1767
@code{BESSEL_JN(N1, N2, X)}
1768
 
1769
@item @emph{Syntax}:
1770
@multitable @columnfractions .80
1771
@item @code{RESULT = BESSEL_JN(N, X)}
1772
@item @code{RESULT = BESSEL_JN(N1, N2, X)}
1773
@end multitable
1774
 
1775
@item @emph{Arguments}:
1776
@multitable @columnfractions .15 .70
1777
@item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1778
@item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1779
@item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1780
@item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1781
for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1782
@end multitable
1783
 
1784
@item @emph{Return value}:
1785
The return value is a scalar of type @code{REAL}. It has the same
1786
kind as @var{X}.
1787
 
1788
@item @emph{Note}:
1789
The transformational function uses a recurrence algorithm which might,
1790
for some values of @var{X}, lead to different results than calls to
1791
the elemental function.
1792
 
1793
@item @emph{Example}:
1794
@smallexample
1795
program test_besjn
1796
  real(8) :: x = 1.0_8
1797
  x = bessel_jn(5,x)
1798
end program test_besjn
1799
@end smallexample
1800
 
1801
@item @emph{Specific names}:
1802
@multitable @columnfractions .20 .20 .20 .25
1803
@item Name                @tab Argument            @tab Return type       @tab Standard
1804
@item @code{DBESJN(N, X)} @tab @code{INTEGER N}    @tab @code{REAL(8)}    @tab GNU extension
1805
@item                     @tab @code{REAL(8) X}    @tab                   @tab
1806
@end multitable
1807
@end table
1808
 
1809
 
1810
 
1811
@node BESSEL_Y0
1812
@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1813
@fnindex BESSEL_Y0
1814
@fnindex BESY0
1815
@fnindex DBESY0
1816
@cindex Bessel function, second kind
1817
 
1818
@table @asis
1819
@item @emph{Description}:
1820
@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1821
order 0 of @var{X}. This function is available under the name
1822
@code{BESY0} as a GNU extension.
1823
 
1824
@item @emph{Standard}:
1825
Fortran 2008 and later
1826
 
1827
@item @emph{Class}:
1828
Elemental function
1829
 
1830
@item @emph{Syntax}:
1831
@code{RESULT = BESSEL_Y0(X)}
1832
 
1833
@item @emph{Arguments}:
1834
@multitable @columnfractions .15 .70
1835
@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1836
@end multitable
1837
 
1838
@item @emph{Return value}:
1839
The return value is a scalar of type @code{REAL}. It has the same
1840
kind as @var{X}.
1841
 
1842
@item @emph{Example}:
1843
@smallexample
1844
program test_besy0
1845
  real(8) :: x = 0.0_8
1846
  x = bessel_y0(x)
1847
end program test_besy0
1848
@end smallexample
1849
 
1850
@item @emph{Specific names}:
1851
@multitable @columnfractions .20 .20 .20 .25
1852
@item Name            @tab Argument          @tab Return type       @tab Standard
1853
@item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1854
@end multitable
1855
@end table
1856
 
1857
 
1858
 
1859
@node BESSEL_Y1
1860
@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1861
@fnindex BESSEL_Y1
1862
@fnindex BESY1
1863
@fnindex DBESY1
1864
@cindex Bessel function, second kind
1865
 
1866
@table @asis
1867
@item @emph{Description}:
1868
@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1869
order 1 of @var{X}. This function is available under the name
1870
@code{BESY1} as a GNU extension.
1871
 
1872
@item @emph{Standard}:
1873
Fortran 2008 and later
1874
 
1875
@item @emph{Class}:
1876
Elemental function
1877
 
1878
@item @emph{Syntax}:
1879
@code{RESULT = BESSEL_Y1(X)}
1880
 
1881
@item @emph{Arguments}:
1882
@multitable @columnfractions .15 .70
1883
@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1884
@end multitable
1885
 
1886
@item @emph{Return value}:
1887
The return value is a scalar of type @code{REAL}. It has the same
1888
kind as @var{X}.
1889
 
1890
@item @emph{Example}:
1891
@smallexample
1892
program test_besy1
1893
  real(8) :: x = 1.0_8
1894
  x = bessel_y1(x)
1895
end program test_besy1
1896
@end smallexample
1897
 
1898
@item @emph{Specific names}:
1899
@multitable @columnfractions .20 .20 .20 .25
1900
@item Name            @tab Argument          @tab Return type       @tab Standard
1901
@item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1902
@end multitable
1903
@end table
1904
 
1905
 
1906
 
1907
@node BESSEL_YN
1908
@section @code{BESSEL_YN} --- Bessel function of the second kind
1909
@fnindex BESSEL_YN
1910
@fnindex BESYN
1911
@fnindex DBESYN
1912
@cindex Bessel function, second kind
1913
 
1914
@table @asis
1915
@item @emph{Description}:
1916
@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1917
order @var{N} of @var{X}. This function is available under the name
1918
@code{BESYN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1919
their ranks and shapes shall conform.
1920
 
1921
@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1922
of the first kind of the orders @var{N1} to @var{N2}.
1923
 
1924
@item @emph{Standard}:
1925
Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1926
 
1927
@item @emph{Class}:
1928
Elemental function, except for the transformational function
1929
@code{BESSEL_YN(N1, N2, X)}
1930
 
1931
@item @emph{Syntax}:
1932
@multitable @columnfractions .80
1933
@item @code{RESULT = BESSEL_YN(N, X)}
1934
@item @code{RESULT = BESSEL_YN(N1, N2, X)}
1935
@end multitable
1936
 
1937
@item @emph{Arguments}:
1938
@multitable @columnfractions .15 .70
1939
@item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER} .
1940
@item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1941
@item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1942
@item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1943
for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1944
@end multitable
1945
 
1946
@item @emph{Return value}:
1947
The return value is a scalar of type @code{REAL}. It has the same
1948
kind as @var{X}.
1949
 
1950
@item @emph{Note}:
1951
The transformational function uses a recurrence algorithm which might,
1952
for some values of @var{X}, lead to different results than calls to
1953
the elemental function.
1954
 
1955
@item @emph{Example}:
1956
@smallexample
1957
program test_besyn
1958
  real(8) :: x = 1.0_8
1959
  x = bessel_yn(5,x)
1960
end program test_besyn
1961
@end smallexample
1962
 
1963
@item @emph{Specific names}:
1964
@multitable @columnfractions .20 .20 .20 .25
1965
@item Name               @tab Argument            @tab Return type     @tab Standard
1966
@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
1967
@item                    @tab @code{REAL(8) X} @tab                 @tab
1968
@end multitable
1969
@end table
1970
 
1971
 
1972
 
1973
@node BGE
1974
@section @code{BGE} --- Bitwise greater than or equal to
1975
@fnindex BGE
1976
@cindex bitwise comparison
1977
 
1978
@table @asis
1979
@item @emph{Description}:
1980
Determines whether an integral is a bitwise greater than or equal to
1981
another.
1982
 
1983
@item @emph{Standard}:
1984
Fortran 2008 and later
1985
 
1986
@item @emph{Class}:
1987
Elemental function
1988
 
1989
@item @emph{Syntax}:
1990
@code{RESULT = BGE(I, J)}
1991
 
1992
@item @emph{Arguments}:
1993
@multitable @columnfractions .15 .70
1994
@item @var{I} @tab Shall be of @code{INTEGER} type.
1995
@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1996
as @var{I}.
1997
@end multitable
1998
 
1999
@item @emph{Return value}:
2000
The return value is of type @code{LOGICAL} and of the default kind.
2001
 
2002
@item @emph{See also}:
2003
@ref{BGT}, @ref{BLE}, @ref{BLT}
2004
@end table
2005
 
2006
 
2007
 
2008
@node BGT
2009
@section @code{BGT} --- Bitwise greater than
2010
@fnindex BGT
2011
@cindex bitwise comparison
2012
 
2013
@table @asis
2014
@item @emph{Description}:
2015
Determines whether an integral is a bitwise greater than another.
2016
 
2017
@item @emph{Standard}:
2018
Fortran 2008 and later
2019
 
2020
@item @emph{Class}:
2021
Elemental function
2022
 
2023
@item @emph{Syntax}:
2024
@code{RESULT = BGT(I, J)}
2025
 
2026
@item @emph{Arguments}:
2027
@multitable @columnfractions .15 .70
2028
@item @var{I} @tab Shall be of @code{INTEGER} type.
2029
@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2030
as @var{I}.
2031
@end multitable
2032
 
2033
@item @emph{Return value}:
2034
The return value is of type @code{LOGICAL} and of the default kind.
2035
 
2036
@item @emph{See also}:
2037
@ref{BGE}, @ref{BLE}, @ref{BLT}
2038
@end table
2039
 
2040
 
2041
 
2042
@node BIT_SIZE
2043
@section @code{BIT_SIZE} --- Bit size inquiry function
2044
@fnindex BIT_SIZE
2045
@cindex bits, number of
2046
@cindex size of a variable, in bits
2047
 
2048
@table @asis
2049
@item @emph{Description}:
2050
@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2051
represented by the type of @var{I}.  The result of @code{BIT_SIZE(I)} is
2052
independent of the actual value of @var{I}.
2053
 
2054
@item @emph{Standard}:
2055
Fortran 95 and later
2056
 
2057
@item @emph{Class}:
2058
Inquiry function
2059
 
2060
@item @emph{Syntax}:
2061
@code{RESULT = BIT_SIZE(I)}
2062
 
2063
@item @emph{Arguments}:
2064
@multitable @columnfractions .15 .70
2065
@item @var{I} @tab The type shall be @code{INTEGER}.
2066
@end multitable
2067
 
2068
@item @emph{Return value}:
2069
The return value is of type @code{INTEGER}
2070
 
2071
@item @emph{Example}:
2072
@smallexample
2073
program test_bit_size
2074
    integer :: i = 123
2075
    integer :: size
2076
    size = bit_size(i)
2077
    print *, size
2078
end program test_bit_size
2079
@end smallexample
2080
@end table
2081
 
2082
 
2083
 
2084
@node BLE
2085
@section @code{BLE} --- Bitwise less than or equal to
2086
@fnindex BLE
2087
@cindex bitwise comparison
2088
 
2089
@table @asis
2090
@item @emph{Description}:
2091
Determines whether an integral is a bitwise less than or equal to
2092
another.
2093
 
2094
@item @emph{Standard}:
2095
Fortran 2008 and later
2096
 
2097
@item @emph{Class}:
2098
Elemental function
2099
 
2100
@item @emph{Syntax}:
2101
@code{RESULT = BLE(I, J)}
2102
 
2103
@item @emph{Arguments}:
2104
@multitable @columnfractions .15 .70
2105
@item @var{I} @tab Shall be of @code{INTEGER} type.
2106
@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2107
as @var{I}.
2108
@end multitable
2109
 
2110
@item @emph{Return value}:
2111
The return value is of type @code{LOGICAL} and of the default kind.
2112
 
2113
@item @emph{See also}:
2114
@ref{BGT}, @ref{BGE}, @ref{BLT}
2115
@end table
2116
 
2117
 
2118
 
2119
@node BLT
2120
@section @code{BLT} --- Bitwise less than
2121
@fnindex BLT
2122
@cindex bitwise comparison
2123
 
2124
@table @asis
2125
@item @emph{Description}:
2126
Determines whether an integral is a bitwise less than another.
2127
 
2128
@item @emph{Standard}:
2129
Fortran 2008 and later
2130
 
2131
@item @emph{Class}:
2132
Elemental function
2133
 
2134
@item @emph{Syntax}:
2135
@code{RESULT = BLT(I, J)}
2136
 
2137
@item @emph{Arguments}:
2138
@multitable @columnfractions .15 .70
2139
@item @var{I} @tab Shall be of @code{INTEGER} type.
2140
@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2141
as @var{I}.
2142
@end multitable
2143
 
2144
@item @emph{Return value}:
2145
The return value is of type @code{LOGICAL} and of the default kind.
2146
 
2147
@item @emph{See also}:
2148
@ref{BGE}, @ref{BGT}, @ref{BLE}
2149
@end table
2150
 
2151
 
2152
 
2153
@node BTEST
2154
@section @code{BTEST} --- Bit test function
2155
@fnindex BTEST
2156
@cindex bits, testing
2157
 
2158
@table @asis
2159
@item @emph{Description}:
2160
@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2161
in @var{I} is set.  The counting of the bits starts at 0.
2162
 
2163
@item @emph{Standard}:
2164
Fortran 95 and later
2165
 
2166
@item @emph{Class}:
2167
Elemental function
2168
 
2169
@item @emph{Syntax}:
2170
@code{RESULT = BTEST(I, POS)}
2171
 
2172
@item @emph{Arguments}:
2173
@multitable @columnfractions .15 .70
2174
@item @var{I} @tab The type shall be @code{INTEGER}.
2175
@item @var{POS} @tab The type shall be @code{INTEGER}.
2176
@end multitable
2177
 
2178
@item @emph{Return value}:
2179
The return value is of type @code{LOGICAL}
2180
 
2181
@item @emph{Example}:
2182
@smallexample
2183
program test_btest
2184
    integer :: i = 32768 + 1024 + 64
2185
    integer :: pos
2186
    logical :: bool
2187
    do pos=0,16
2188
        bool = btest(i, pos)
2189
        print *, pos, bool
2190
    end do
2191
end program test_btest
2192
@end smallexample
2193
@end table
2194
 
2195
 
2196
@node C_ASSOCIATED
2197
@section @code{C_ASSOCIATED} --- Status of a C pointer
2198
@fnindex C_ASSOCIATED
2199
@cindex association status, C pointer
2200
@cindex pointer, C association status
2201
 
2202
@table @asis
2203
@item @emph{Description}:
2204
@code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2205
@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2206
 
2207
@item @emph{Standard}:
2208
Fortran 2003 and later
2209
 
2210
@item @emph{Class}:
2211
Inquiry function
2212
 
2213
@item @emph{Syntax}:
2214
@code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2215
 
2216
@item @emph{Arguments}:
2217
@multitable @columnfractions .15 .70
2218
@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2219
@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2220
@end multitable
2221
 
2222
@item @emph{Return value}:
2223
The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2224
@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2225
point to different addresses.
2226
 
2227
@item @emph{Example}:
2228
@smallexample
2229
subroutine association_test(a,b)
2230
  use iso_c_binding, only: c_associated, c_loc, c_ptr
2231
  implicit none
2232
  real, pointer :: a
2233
  type(c_ptr) :: b
2234
  if(c_associated(b, c_loc(a))) &
2235
     stop 'b and a do not point to same target'
2236
end subroutine association_test
2237
@end smallexample
2238
 
2239
@item @emph{See also}:
2240
@ref{C_LOC}, @ref{C_FUNLOC}
2241
@end table
2242
 
2243
 
2244
@node C_FUNLOC
2245
@section @code{C_FUNLOC} --- Obtain the C address of a procedure
2246
@fnindex C_FUNLOC
2247
@cindex pointer, C address of procedures
2248
 
2249
@table @asis
2250
@item @emph{Description}:
2251
@code{C_FUNLOC(x)} determines the C address of the argument.
2252
 
2253
@item @emph{Standard}:
2254
Fortran 2003 and later
2255
 
2256
@item @emph{Class}:
2257
Inquiry function
2258
 
2259
@item @emph{Syntax}:
2260
@code{RESULT = C_FUNLOC(x)}
2261
 
2262
@item @emph{Arguments}:
2263
@multitable @columnfractions .15 .70
2264
@item @var{x} @tab Interoperable function or pointer to such function.
2265
@end multitable
2266
 
2267
@item @emph{Return value}:
2268
The return value is of type @code{C_FUNPTR} and contains the C address
2269
of the argument.
2270
 
2271
@item @emph{Example}:
2272
@smallexample
2273
module x
2274
  use iso_c_binding
2275
  implicit none
2276
contains
2277
  subroutine sub(a) bind(c)
2278
    real(c_float) :: a
2279
    a = sqrt(a)+5.0
2280
  end subroutine sub
2281
end module x
2282
program main
2283
  use iso_c_binding
2284
  use x
2285
  implicit none
2286
  interface
2287
    subroutine my_routine(p) bind(c,name='myC_func')
2288
      import :: c_funptr
2289
      type(c_funptr), intent(in) :: p
2290
    end subroutine
2291
  end interface
2292
  call my_routine(c_funloc(sub))
2293
end program main
2294
@end smallexample
2295
 
2296
@item @emph{See also}:
2297
@ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2298
@end table
2299
 
2300
 
2301
@node C_F_PROCPOINTER
2302
@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2303
@fnindex C_F_PROCPOINTER
2304
@cindex pointer, C address of pointers
2305
 
2306
@table @asis
2307
@item @emph{Description}:
2308
@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2309
@var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2310
 
2311
@item @emph{Standard}:
2312
Fortran 2003 and later
2313
 
2314
@item @emph{Class}:
2315
Subroutine
2316
 
2317
@item @emph{Syntax}:
2318
@code{CALL C_F_PROCPOINTER(cptr, fptr)}
2319
 
2320
@item @emph{Arguments}:
2321
@multitable @columnfractions .15 .70
2322
@item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
2323
@code{INTENT(IN)}.
2324
@item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
2325
@code{INTENT(OUT)}.
2326
@end multitable
2327
 
2328
@item @emph{Example}:
2329
@smallexample
2330
program main
2331
  use iso_c_binding
2332
  implicit none
2333
  abstract interface
2334
    function func(a)
2335
      import :: c_float
2336
      real(c_float), intent(in) :: a
2337
      real(c_float) :: func
2338
    end function
2339
  end interface
2340
  interface
2341
     function getIterFunc() bind(c,name="getIterFunc")
2342
       import :: c_funptr
2343
       type(c_funptr) :: getIterFunc
2344
     end function
2345
  end interface
2346
  type(c_funptr) :: cfunptr
2347
  procedure(func), pointer :: myFunc
2348
  cfunptr = getIterFunc()
2349
  call c_f_procpointer(cfunptr, myFunc)
2350
end program main
2351
@end smallexample
2352
 
2353
@item @emph{See also}:
2354
@ref{C_LOC}, @ref{C_F_POINTER}
2355
@end table
2356
 
2357
 
2358
@node C_F_POINTER
2359
@section @code{C_F_POINTER} --- Convert C into Fortran pointer
2360
@fnindex C_F_POINTER
2361
@cindex pointer, convert C to Fortran
2362
 
2363
@table @asis
2364
@item @emph{Description}:
2365
@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2366
@var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2367
shape.
2368
 
2369
@item @emph{Standard}:
2370
Fortran 2003 and later
2371
 
2372
@item @emph{Class}:
2373
Subroutine
2374
 
2375
@item @emph{Syntax}:
2376
@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2377
 
2378
@item @emph{Arguments}:
2379
@multitable @columnfractions .15 .70
2380
@item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
2381
@code{INTENT(IN)}.
2382
@item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
2383
@code{INTENT(OUT)}.
2384
@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2385
with @code{INTENT(IN)}. It shall be present
2386
if and only if @var{fptr} is an array. The size
2387
must be equal to the rank of @var{fptr}.
2388
@end multitable
2389
 
2390
@item @emph{Example}:
2391
@smallexample
2392
program main
2393
  use iso_c_binding
2394
  implicit none
2395
  interface
2396
    subroutine my_routine(p) bind(c,name='myC_func')
2397
      import :: c_ptr
2398
      type(c_ptr), intent(out) :: p
2399
    end subroutine
2400
  end interface
2401
  type(c_ptr) :: cptr
2402
  real,pointer :: a(:)
2403
  call my_routine(cptr)
2404
  call c_f_pointer(cptr, a, [12])
2405
end program main
2406
@end smallexample
2407
 
2408
@item @emph{See also}:
2409
@ref{C_LOC}, @ref{C_F_PROCPOINTER}
2410
@end table
2411
 
2412
 
2413
@node C_LOC
2414
@section @code{C_LOC} --- Obtain the C address of an object
2415
@fnindex C_LOC
2416
@cindex procedure pointer, convert C to Fortran
2417
 
2418
@table @asis
2419
@item @emph{Description}:
2420
@code{C_LOC(X)} determines the C address of the argument.
2421
 
2422
@item @emph{Standard}:
2423
Fortran 2003 and later
2424
 
2425
@item @emph{Class}:
2426
Inquiry function
2427
 
2428
@item @emph{Syntax}:
2429
@code{RESULT = C_LOC(X)}
2430
 
2431
@item @emph{Arguments}:
2432
@multitable @columnfractions .10 .75
2433
@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.
2434
 
2435
@end multitable
2436
 
2437
@item @emph{Return value}:
2438
The return value is of type @code{C_PTR} and contains the C address
2439
of the argument.
2440
 
2441
@item @emph{Example}:
2442
@smallexample
2443
subroutine association_test(a,b)
2444
  use iso_c_binding, only: c_associated, c_loc, c_ptr
2445
  implicit none
2446
  real, pointer :: a
2447
  type(c_ptr) :: b
2448
  if(c_associated(b, c_loc(a))) &
2449
     stop 'b and a do not point to same target'
2450
end subroutine association_test
2451
@end smallexample
2452
 
2453
@item @emph{See also}:
2454
@ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2455
@end table
2456
 
2457
 
2458
@node C_SIZEOF
2459
@section @code{C_SIZEOF} --- Size in bytes of an expression
2460
@fnindex C_SIZEOF
2461
@cindex expression size
2462
@cindex size of an expression
2463
 
2464
@table @asis
2465
@item @emph{Description}:
2466
@code{C_SIZEOF(X)} calculates the number of bytes of storage the
2467
expression @code{X} occupies.
2468
 
2469
@item @emph{Standard}:
2470
Fortran 2008
2471
 
2472
@item @emph{Class}:
2473
Inquiry function of the module @code{ISO_C_BINDING}
2474
 
2475
@item @emph{Syntax}:
2476
@code{N = C_SIZEOF(X)}
2477
 
2478
@item @emph{Arguments}:
2479
@multitable @columnfractions .15 .70
2480
@item @var{X} @tab The argument shall be an interoperable data entity.
2481
@end multitable
2482
 
2483
@item @emph{Return value}:
2484
The return value is of type integer and of the system-dependent kind
2485
@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2486
number of bytes occupied by the argument.  If the argument has the
2487
@code{POINTER} attribute, the number of bytes of the storage area pointed
2488
to is returned.  If the argument is of a derived type with @code{POINTER}
2489
or @code{ALLOCATABLE} components, the return value does not account for
2490
the sizes of the data pointed to by these components.
2491
 
2492
@item @emph{Example}:
2493
@smallexample
2494
   use iso_c_binding
2495
   integer(c_int) :: i
2496
   real(c_float) :: r, s(5)
2497
   print *, (c_sizeof(s)/c_sizeof(r) == 5)
2498
   end
2499
@end smallexample
2500
The example will print @code{.TRUE.} unless you are using a platform
2501
where default @code{REAL} variables are unusually padded.
2502
 
2503
@item @emph{See also}:
2504
@ref{SIZEOF}, @ref{STORAGE_SIZE}
2505
@end table
2506
 
2507
 
2508
@node CEILING
2509
@section @code{CEILING} --- Integer ceiling function
2510
@fnindex CEILING
2511
@cindex ceiling
2512
@cindex rounding, ceiling
2513
 
2514
@table @asis
2515
@item @emph{Description}:
2516
@code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2517
 
2518
@item @emph{Standard}:
2519
Fortran 95 and later
2520
 
2521
@item @emph{Class}:
2522
Elemental function
2523
 
2524
@item @emph{Syntax}:
2525
@code{RESULT = CEILING(A [, KIND])}
2526
 
2527
@item @emph{Arguments}:
2528
@multitable @columnfractions .15 .70
2529
@item @var{A} @tab The type shall be @code{REAL}.
2530
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2531
expression indicating the kind parameter of the result.
2532
@end multitable
2533
 
2534
@item @emph{Return value}:
2535
The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2536
and a default-kind @code{INTEGER} otherwise.
2537
 
2538
@item @emph{Example}:
2539
@smallexample
2540
program test_ceiling
2541
    real :: x = 63.29
2542
    real :: y = -63.59
2543
    print *, ceiling(x) ! returns 64
2544
    print *, ceiling(y) ! returns -63
2545
end program test_ceiling
2546
@end smallexample
2547
 
2548
@item @emph{See also}:
2549
@ref{FLOOR}, @ref{NINT}
2550
 
2551
@end table
2552
 
2553
 
2554
 
2555
@node CHAR
2556
@section @code{CHAR} --- Character conversion function
2557
@fnindex CHAR
2558
@cindex conversion, to character
2559
 
2560
@table @asis
2561
@item @emph{Description}:
2562
@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2563
 
2564
@item @emph{Standard}:
2565
Fortran 77 and later
2566
 
2567
@item @emph{Class}:
2568
Elemental function
2569
 
2570
@item @emph{Syntax}:
2571
@code{RESULT = CHAR(I [, KIND])}
2572
 
2573
@item @emph{Arguments}:
2574
@multitable @columnfractions .15 .70
2575
@item @var{I} @tab The type shall be @code{INTEGER}.
2576
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2577
expression indicating the kind parameter of the result.
2578
@end multitable
2579
 
2580
@item @emph{Return value}:
2581
The return value is of type @code{CHARACTER(1)}
2582
 
2583
@item @emph{Example}:
2584
@smallexample
2585
program test_char
2586
    integer :: i = 74
2587
    character(1) :: c
2588
    c = char(i)
2589
    print *, i, c ! returns 'J'
2590
end program test_char
2591
@end smallexample
2592
 
2593
@item @emph{Specific names}:
2594
@multitable @columnfractions .20 .20 .20 .25
2595
@item Name           @tab Argument         @tab Return type             @tab Standard
2596
@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2597
@end multitable
2598
 
2599
@item @emph{Note}:
2600
See @ref{ICHAR} for a discussion of converting between numerical values
2601
and formatted string representations.
2602
 
2603
@item @emph{See also}:
2604
@ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2605
 
2606
@end table
2607
 
2608
 
2609
 
2610
@node CHDIR
2611
@section @code{CHDIR} --- Change working directory
2612
@fnindex CHDIR
2613
@cindex system, working directory
2614
 
2615
@table @asis
2616
@item @emph{Description}:
2617
Change current working directory to a specified path.
2618
 
2619
This intrinsic is provided in both subroutine and function forms; however,
2620
only one form can be used in any given program unit.
2621
 
2622
@item @emph{Standard}:
2623
GNU extension
2624
 
2625
@item @emph{Class}:
2626
Subroutine, function
2627
 
2628
@item @emph{Syntax}:
2629
@multitable @columnfractions .80
2630
@item @code{CALL CHDIR(NAME [, STATUS])}
2631
@item @code{STATUS = CHDIR(NAME)}
2632
@end multitable
2633
 
2634
@item @emph{Arguments}:
2635
@multitable @columnfractions .15 .70
2636
@item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
2637
kind and shall specify a valid path within the file system.
2638
@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2639
kind.  Returns 0 on success, and a system specific and nonzero error code
2640
otherwise.
2641
@end multitable
2642
 
2643
@item @emph{Example}:
2644
@smallexample
2645
PROGRAM test_chdir
2646
  CHARACTER(len=255) :: path
2647
  CALL getcwd(path)
2648
  WRITE(*,*) TRIM(path)
2649
  CALL chdir("/tmp")
2650
  CALL getcwd(path)
2651
  WRITE(*,*) TRIM(path)
2652
END PROGRAM
2653
@end smallexample
2654
 
2655
@item @emph{See also}:
2656
@ref{GETCWD}
2657
@end table
2658
 
2659
 
2660
 
2661
@node CHMOD
2662
@section @code{CHMOD} --- Change access permissions of files
2663
@fnindex CHMOD
2664
@cindex file system, change access mode
2665
 
2666
@table @asis
2667
@item @emph{Description}:
2668
@code{CHMOD} changes the permissions of a file.
2669
 
2670
This intrinsic is provided in both subroutine and function forms; however,
2671
only one form can be used in any given program unit.
2672
 
2673
@item @emph{Standard}:
2674
GNU extension
2675
 
2676
@item @emph{Class}:
2677
Subroutine, function
2678
 
2679
@item @emph{Syntax}:
2680
@multitable @columnfractions .80
2681
@item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2682
@item @code{STATUS = CHMOD(NAME, MODE)}
2683
@end multitable
2684
 
2685
@item @emph{Arguments}:
2686
@multitable @columnfractions .15 .70
2687
 
2688
@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2689
file name. Trailing blanks are ignored unless the character
2690
@code{achar(0)} is present, then all characters up to and excluding
2691
@code{achar(0)} are used as the file name.
2692
 
2693
@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2694
file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
2695
as defined by the POSIX standard. The argument shall either be a string of
2696
a nonnegative octal number or a symbolic mode.
2697
 
2698
@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2699
@code{0} on success and nonzero otherwise.
2700
@end multitable
2701
 
2702
@item @emph{Return value}:
2703
In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2704
otherwise.
2705
 
2706
@item @emph{Example}:
2707
@code{CHMOD} as subroutine
2708
@smallexample
2709
program chmod_test
2710
  implicit none
2711
  integer :: status
2712
  call chmod('test.dat','u+x',status)
2713
  print *, 'Status: ', status
2714
end program chmod_test
2715
@end smallexample
2716
@code{CHMOD} as function:
2717
@smallexample
2718
program chmod_test
2719
  implicit none
2720
  integer :: status
2721
  status = chmod('test.dat','u+x')
2722
  print *, 'Status: ', status
2723
end program chmod_test
2724
@end smallexample
2725
 
2726
@end table
2727
 
2728
 
2729
 
2730
@node CMPLX
2731
@section @code{CMPLX} --- Complex conversion function
2732
@fnindex CMPLX
2733
@cindex complex numbers, conversion to
2734
@cindex conversion, to complex
2735
 
2736
@table @asis
2737
@item @emph{Description}:
2738
@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2739
the real component.  If @var{Y} is present it is converted to the imaginary
2740
component.  If @var{Y} is not present then the imaginary component is set to
2741
0.0.  If @var{X} is complex then @var{Y} must not be present.
2742
 
2743
@item @emph{Standard}:
2744
Fortran 77 and later
2745
 
2746
@item @emph{Class}:
2747
Elemental function
2748
 
2749
@item @emph{Syntax}:
2750
@code{RESULT = CMPLX(X [, Y [, KIND]])}
2751
 
2752
@item @emph{Arguments}:
2753
@multitable @columnfractions .15 .70
2754
@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2755
or @code{COMPLEX}.
2756
@item @var{Y} @tab (Optional; only allowed if @var{X} is not
2757
@code{COMPLEX}.)  May be @code{INTEGER} or @code{REAL}.
2758
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2759
expression indicating the kind parameter of the result.
2760
@end multitable
2761
 
2762
@item @emph{Return value}:
2763
The return value is of @code{COMPLEX} type, with a kind equal to
2764
@var{KIND} if it is specified.  If @var{KIND} is not specified, the
2765
result is of the default @code{COMPLEX} kind, regardless of the kinds of
2766
@var{X} and @var{Y}.
2767
 
2768
@item @emph{Example}:
2769
@smallexample
2770
program test_cmplx
2771
    integer :: i = 42
2772
    real :: x = 3.14
2773
    complex :: z
2774
    z = cmplx(i, x)
2775
    print *, z, cmplx(x)
2776
end program test_cmplx
2777
@end smallexample
2778
 
2779
@item @emph{See also}:
2780
@ref{COMPLEX}
2781
@end table
2782
 
2783
 
2784
 
2785
@node COMMAND_ARGUMENT_COUNT
2786
@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2787
@fnindex COMMAND_ARGUMENT_COUNT
2788
@cindex command-line arguments
2789
@cindex command-line arguments, number of
2790
@cindex arguments, to program
2791
 
2792
@table @asis
2793
@item @emph{Description}:
2794
@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
2795
command line when the containing program was invoked.
2796
 
2797
@item @emph{Standard}:
2798
Fortran 2003 and later
2799
 
2800
@item @emph{Class}:
2801
Inquiry function
2802
 
2803
@item @emph{Syntax}:
2804
@code{RESULT = COMMAND_ARGUMENT_COUNT()}
2805
 
2806
@item @emph{Arguments}:
2807
@multitable @columnfractions .15 .70
2808
@item None
2809
@end multitable
2810
 
2811
@item @emph{Return value}:
2812
The return value is an @code{INTEGER} of default kind.
2813
 
2814
@item @emph{Example}:
2815
@smallexample
2816
program test_command_argument_count
2817
    integer :: count
2818
    count = command_argument_count()
2819
    print *, count
2820
end program test_command_argument_count
2821
@end smallexample
2822
 
2823
@item @emph{See also}:
2824
@ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2825
@end table
2826
 
2827
 
2828
 
2829
@node COMPILER_OPTIONS
2830
@section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2831
@fnindex COMPILER_OPTIONS
2832
@cindex flags inquiry function
2833
@cindex options inquiry function
2834
@cindex compiler flags inquiry function
2835
 
2836
@table @asis
2837
@item @emph{Description}:
2838
@code{COMPILER_OPTIONS} returns a string with the options used for
2839
compiling.
2840
 
2841
@item @emph{Standard}:
2842
Fortran 2008
2843
 
2844
@item @emph{Class}:
2845
Inquiry function of the module @code{ISO_FORTRAN_ENV}
2846
 
2847
@item @emph{Syntax}:
2848
@code{STR = COMPILER_OPTIONS()}
2849
 
2850
@item @emph{Arguments}:
2851
None.
2852
 
2853
@item @emph{Return value}:
2854
The return value is a default-kind string with system-dependent length.
2855
It contains the compiler flags used to compile the file, which called
2856
the @code{COMPILER_OPTIONS} intrinsic.
2857
 
2858
@item @emph{Example}:
2859
@smallexample
2860
   use iso_fortran_env
2861
   print '(4a)', 'This file was compiled by ', &
2862
                 compiler_version(), ' using the options ', &
2863
                 compiler_options()
2864
   end
2865
@end smallexample
2866
 
2867
@item @emph{See also}:
2868
@ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2869
@end table
2870
 
2871
 
2872
 
2873
@node COMPILER_VERSION
2874
@section @code{COMPILER_VERSION} --- Compiler version string
2875
@fnindex COMPILER_VERSION
2876
@cindex compiler, name and version
2877
@cindex version of the compiler
2878
 
2879
@table @asis
2880
@item @emph{Description}:
2881
@code{COMPILER_VERSION} returns a string with the name and the
2882
version of the compiler.
2883
 
2884
@item @emph{Standard}:
2885
Fortran 2008
2886
 
2887
@item @emph{Class}:
2888
Inquiry function of the module @code{ISO_FORTRAN_ENV}
2889
 
2890
@item @emph{Syntax}:
2891
@code{STR = COMPILER_VERSION()}
2892
 
2893
@item @emph{Arguments}:
2894
None.
2895
 
2896
@item @emph{Return value}:
2897
The return value is a default-kind string with system-dependent length.
2898
It contains the name of the compiler and its version number.
2899
 
2900
@item @emph{Example}:
2901
@smallexample
2902
   use iso_fortran_env
2903
   print '(4a)', 'This file was compiled by ', &
2904
                 compiler_version(), ' using the options ', &
2905
                 compiler_options()
2906
   end
2907
@end smallexample
2908
 
2909
@item @emph{See also}:
2910
@ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2911
@end table
2912
 
2913
 
2914
 
2915
@node COMPLEX
2916
@section @code{COMPLEX} --- Complex conversion function
2917
@fnindex COMPLEX
2918
@cindex complex numbers, conversion to
2919
@cindex conversion, to complex
2920
 
2921
@table @asis
2922
@item @emph{Description}:
2923
@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2924
to the real component and @var{Y} is converted to the imaginary
2925
component.
2926
 
2927
@item @emph{Standard}:
2928
GNU extension
2929
 
2930
@item @emph{Class}:
2931
Elemental function
2932
 
2933
@item @emph{Syntax}:
2934
@code{RESULT = COMPLEX(X, Y)}
2935
 
2936
@item @emph{Arguments}:
2937
@multitable @columnfractions .15 .70
2938
@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2939
@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2940
@end multitable
2941
 
2942
@item @emph{Return value}:
2943
If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2944
value is of default @code{COMPLEX} type.
2945
 
2946
If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2947
type and one is of @code{INTEGER} type, then the return value is of
2948
@code{COMPLEX} type with a kind equal to that of the @code{REAL}
2949
argument with the highest precision.
2950
 
2951
@item @emph{Example}:
2952
@smallexample
2953
program test_complex
2954
    integer :: i = 42
2955
    real :: x = 3.14
2956
    print *, complex(i, x)
2957
end program test_complex
2958
@end smallexample
2959
 
2960
@item @emph{See also}:
2961
@ref{CMPLX}
2962
@end table
2963
 
2964
 
2965
 
2966
@node CONJG
2967
@section @code{CONJG} --- Complex conjugate function
2968
@fnindex CONJG
2969
@fnindex DCONJG
2970
@cindex complex conjugate
2971
 
2972
@table @asis
2973
@item @emph{Description}:
2974
@code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2975
then the result is @code{(x, -y)}
2976
 
2977
@item @emph{Standard}:
2978
Fortran 77 and later, has overloads that are GNU extensions
2979
 
2980
@item @emph{Class}:
2981
Elemental function
2982
 
2983
@item @emph{Syntax}:
2984
@code{Z = CONJG(Z)}
2985
 
2986
@item @emph{Arguments}:
2987
@multitable @columnfractions .15 .70
2988
@item @var{Z} @tab The type shall be @code{COMPLEX}.
2989
@end multitable
2990
 
2991
@item @emph{Return value}:
2992
The return value is of type @code{COMPLEX}.
2993
 
2994
@item @emph{Example}:
2995
@smallexample
2996
program test_conjg
2997
    complex :: z = (2.0, 3.0)
2998
    complex(8) :: dz = (2.71_8, -3.14_8)
2999
    z= conjg(z)
3000
    print *, z
3001
    dz = dconjg(dz)
3002
    print *, dz
3003
end program test_conjg
3004
@end smallexample
3005
 
3006
@item @emph{Specific names}:
3007
@multitable @columnfractions .20 .20 .20 .25
3008
@item Name             @tab Argument             @tab Return type       @tab Standard
3009
@item @code{CONJG(Z)}  @tab @code{COMPLEX Z}     @tab @code{COMPLEX}    @tab GNU extension
3010
@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)} @tab GNU extension
3011
@end multitable
3012
@end table
3013
 
3014
 
3015
 
3016
@node COS
3017
@section @code{COS} --- Cosine function
3018
@fnindex COS
3019
@fnindex DCOS
3020
@fnindex CCOS
3021
@fnindex ZCOS
3022
@fnindex CDCOS
3023
@cindex trigonometric function, cosine
3024
@cindex cosine
3025
 
3026
@table @asis
3027
@item @emph{Description}:
3028
@code{COS(X)} computes the cosine of @var{X}.
3029
 
3030
@item @emph{Standard}:
3031
Fortran 77 and later, has overloads that are GNU extensions
3032
 
3033
@item @emph{Class}:
3034
Elemental function
3035
 
3036
@item @emph{Syntax}:
3037
@code{RESULT = COS(X)}
3038
 
3039
@item @emph{Arguments}:
3040
@multitable @columnfractions .15 .70
3041
@item @var{X} @tab The type shall be @code{REAL} or
3042
@code{COMPLEX}.
3043
@end multitable
3044
 
3045
@item @emph{Return value}:
3046
The return value is of the same type and kind as @var{X}. The real part
3047
of the result is in radians. If @var{X} is of the type @code{REAL},
3048
the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3049
 
3050
@item @emph{Example}:
3051
@smallexample
3052
program test_cos
3053
  real :: x = 0.0
3054
  x = cos(x)
3055
end program test_cos
3056
@end smallexample
3057
 
3058
@item @emph{Specific names}:
3059
@multitable @columnfractions .20 .20 .20 .25
3060
@item Name            @tab Argument            @tab Return type       @tab Standard
3061
@item @code{COS(X)}   @tab @code{REAL(4) X}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3062
@item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3063
@item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3064
@item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3065
@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3066
@end multitable
3067
 
3068
@item @emph{See also}:
3069
Inverse function: @ref{ACOS}
3070
 
3071
@end table
3072
 
3073
 
3074
 
3075
@node COSH
3076
@section @code{COSH} --- Hyperbolic cosine function
3077
@fnindex COSH
3078
@fnindex DCOSH
3079
@cindex hyperbolic cosine
3080
@cindex hyperbolic function, cosine
3081
@cindex cosine, hyperbolic
3082
 
3083
@table @asis
3084
@item @emph{Description}:
3085
@code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3086
 
3087
@item @emph{Standard}:
3088
Fortran 77 and later, for a complex argument Fortran 2008 or later
3089
 
3090
@item @emph{Class}:
3091
Elemental function
3092
 
3093
@item @emph{Syntax}:
3094
@code{X = COSH(X)}
3095
 
3096
@item @emph{Arguments}:
3097
@multitable @columnfractions .15 .70
3098
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3099
@end multitable
3100
 
3101
@item @emph{Return value}:
3102
The return value has same type and kind as @var{X}. If @var{X} is
3103
complex, the imaginary part of the result is in radians. If @var{X}
3104
is @code{REAL}, the return value has a lower bound of one,
3105
@math{\cosh (x) \geq 1}.
3106
 
3107
@item @emph{Example}:
3108
@smallexample
3109
program test_cosh
3110
  real(8) :: x = 1.0_8
3111
  x = cosh(x)
3112
end program test_cosh
3113
@end smallexample
3114
 
3115
@item @emph{Specific names}:
3116
@multitable @columnfractions .20 .20 .20 .25
3117
@item Name            @tab Argument          @tab Return type       @tab Standard
3118
@item @code{COSH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
3119
@item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
3120
@end multitable
3121
 
3122
@item @emph{See also}:
3123
Inverse function: @ref{ACOSH}
3124
 
3125
@end table
3126
 
3127
 
3128
 
3129
@node COUNT
3130
@section @code{COUNT} --- Count function
3131
@fnindex COUNT
3132
@cindex array, conditionally count elements
3133
@cindex array, element counting
3134
@cindex array, number of elements
3135
 
3136
@table @asis
3137
@item @emph{Description}:
3138
 
3139
Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3140
or, if the @var{DIM} argument is supplied, counts the number of
3141
elements along each row of the array in the @var{DIM} direction.
3142
If the array has zero size, or all of the elements of @var{MASK} are
3143
@code{.FALSE.}, then the result is @code{0}.
3144
 
3145
@item @emph{Standard}:
3146
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3147
 
3148
@item @emph{Class}:
3149
Transformational function
3150
 
3151
@item @emph{Syntax}:
3152
@code{RESULT = COUNT(MASK [, DIM, KIND])}
3153
 
3154
@item @emph{Arguments}:
3155
@multitable @columnfractions .15 .70
3156
@item @var{MASK} @tab The type shall be @code{LOGICAL}.
3157
@item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
3158
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3159
expression indicating the kind parameter of the result.
3160
@end multitable
3161
 
3162
@item @emph{Return value}:
3163
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3164
@var{KIND} is absent, the return value is of default integer kind.
3165
If @var{DIM} is present, the result is an array with a rank one less
3166
than the rank of @var{ARRAY}, and a size corresponding to the shape
3167
of @var{ARRAY} with the @var{DIM} dimension removed.
3168
 
3169
@item @emph{Example}:
3170
@smallexample
3171
program test_count
3172
    integer, dimension(2,3) :: a, b
3173
    logical, dimension(2,3) :: mask
3174
    a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3175
    b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3176
    print '(3i3)', a(1,:)
3177
    print '(3i3)', a(2,:)
3178
    print *
3179
    print '(3i3)', b(1,:)
3180
    print '(3i3)', b(2,:)
3181
    print *
3182
    mask = a.ne.b
3183
    print '(3l3)', mask(1,:)
3184
    print '(3l3)', mask(2,:)
3185
    print *
3186
    print '(3i3)', count(mask)
3187
    print *
3188
    print '(3i3)', count(mask, 1)
3189
    print *
3190
    print '(3i3)', count(mask, 2)
3191
end program test_count
3192
@end smallexample
3193
@end table
3194
 
3195
 
3196
 
3197
@node CPU_TIME
3198
@section @code{CPU_TIME} --- CPU elapsed time in seconds
3199
@fnindex CPU_TIME
3200
@cindex time, elapsed
3201
 
3202
@table @asis
3203
@item @emph{Description}:
3204
Returns a @code{REAL} value representing the elapsed CPU time in
3205
seconds.  This is useful for testing segments of code to determine
3206
execution time.
3207
 
3208
If a time source is available, time will be reported with microsecond
3209
resolution. If no time source is available, @var{TIME} is set to
3210
@code{-1.0}.
3211
 
3212
Note that @var{TIME} may contain a, system dependent, arbitrary offset
3213
and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3214
value is meaningless, only differences between subsequent calls to
3215
this subroutine, as shown in the example below, should be used.
3216
 
3217
 
3218
@item @emph{Standard}:
3219
Fortran 95 and later
3220
 
3221
@item @emph{Class}:
3222
Subroutine
3223
 
3224
@item @emph{Syntax}:
3225
@code{CALL CPU_TIME(TIME)}
3226
 
3227
@item @emph{Arguments}:
3228
@multitable @columnfractions .15 .70
3229
@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3230
@end multitable
3231
 
3232
@item @emph{Return value}:
3233
None
3234
 
3235
@item @emph{Example}:
3236
@smallexample
3237
program test_cpu_time
3238
    real :: start, finish
3239
    call cpu_time(start)
3240
        ! put code to test here
3241
    call cpu_time(finish)
3242
    print '("Time = ",f6.3," seconds.")',finish-start
3243
end program test_cpu_time
3244
@end smallexample
3245
 
3246
@item @emph{See also}:
3247
@ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3248
@end table
3249
 
3250
 
3251
 
3252
@node CSHIFT
3253
@section @code{CSHIFT} --- Circular shift elements of an array
3254
@fnindex CSHIFT
3255
@cindex array, shift circularly
3256
@cindex array, permutation
3257
@cindex array, rotate
3258
 
3259
@table @asis
3260
@item @emph{Description}:
3261
@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3262
@var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
3263
taken to be @code{1}.  @var{DIM} is a scalar of type @code{INTEGER} in the
3264
range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3265
If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3266
by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
3267
sections of @var{ARRAY} along the given dimension are shifted.  Elements
3268
shifted out one end of each rank one section are shifted back in the other end.
3269
 
3270
@item @emph{Standard}:
3271
Fortran 95 and later
3272
 
3273
@item @emph{Class}:
3274
Transformational function
3275
 
3276
@item @emph{Syntax}:
3277
@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3278
 
3279
@item @emph{Arguments}:
3280
@multitable @columnfractions .15 .70
3281
@item @var{ARRAY}  @tab Shall be an array of any type.
3282
@item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3283
@item @var{DIM}    @tab The type shall be @code{INTEGER}.
3284
@end multitable
3285
 
3286
@item @emph{Return value}:
3287
Returns an array of same type and rank as the @var{ARRAY} argument.
3288
 
3289
@item @emph{Example}:
3290
@smallexample
3291
program test_cshift
3292
    integer, dimension(3,3) :: a
3293
    a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3294
    print '(3i3)', a(1,:)
3295
    print '(3i3)', a(2,:)
3296
    print '(3i3)', a(3,:)
3297
    a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3298
    print *
3299
    print '(3i3)', a(1,:)
3300
    print '(3i3)', a(2,:)
3301
    print '(3i3)', a(3,:)
3302
end program test_cshift
3303
@end smallexample
3304
@end table
3305
 
3306
 
3307
 
3308
@node CTIME
3309
@section @code{CTIME} --- Convert a time into a string
3310
@fnindex CTIME
3311
@cindex time, conversion to string
3312
@cindex conversion, to string
3313
 
3314
@table @asis
3315
@item @emph{Description}:
3316
@code{CTIME} converts a system time value, such as returned by
3317
@code{TIME8}, to a string. Unless the application has called
3318
@code{setlocale}, the output will be in the default locale, of length
3319
24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
3320
a longer string may result.
3321
 
3322
This intrinsic is provided in both subroutine and function forms; however,
3323
only one form can be used in any given program unit.
3324
 
3325
@item @emph{Standard}:
3326
GNU extension
3327
 
3328
@item @emph{Class}:
3329
Subroutine, function
3330
 
3331
@item @emph{Syntax}:
3332
@multitable @columnfractions .80
3333
@item @code{CALL CTIME(TIME, RESULT)}.
3334
@item @code{RESULT = CTIME(TIME)}.
3335
@end multitable
3336
 
3337
@item @emph{Arguments}:
3338
@multitable @columnfractions .15 .70
3339
@item @var{TIME}    @tab The type shall be of type @code{INTEGER}.
3340
@item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
3341
of default kind. It is an @code{INTENT(OUT)} argument. If the length
3342
of this variable is too short for the time and date string to fit
3343
completely, it will be blank on procedure return.
3344
@end multitable
3345
 
3346
@item @emph{Return value}:
3347
The converted date and time as a string.
3348
 
3349
@item @emph{Example}:
3350
@smallexample
3351
program test_ctime
3352
    integer(8) :: i
3353
    character(len=30) :: date
3354
    i = time8()
3355
 
3356
    ! Do something, main part of the program
3357
 
3358
    call ctime(i,date)
3359
    print *, 'Program was started on ', date
3360
end program test_ctime
3361
@end smallexample
3362
 
3363
@item @emph{See Also}:
3364
@ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3365
@end table
3366
 
3367
 
3368
 
3369
@node DATE_AND_TIME
3370
@section @code{DATE_AND_TIME} --- Date and time subroutine
3371
@fnindex DATE_AND_TIME
3372
@cindex date, current
3373
@cindex current date
3374
@cindex time, current
3375
@cindex current time
3376
 
3377
@table @asis
3378
@item @emph{Description}:
3379
@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3380
time information from the real-time system clock.  @var{DATE} is
3381
@code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
3382
has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3383
representing the difference with respect to Coordinated Universal Time (UTC).
3384
Unavailable time and date parameters return blanks.
3385
 
3386
@var{VALUES} is @code{INTENT(OUT)} and provides the following:
3387
 
3388
@multitable @columnfractions .15 .30 .40
3389
@item @tab @code{VALUE(1)}: @tab The year
3390
@item @tab @code{VALUE(2)}: @tab The month
3391
@item @tab @code{VALUE(3)}: @tab The day of the month
3392
@item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3393
@item @tab @code{VALUE(5)}: @tab The hour of the day
3394
@item @tab @code{VALUE(6)}: @tab The minutes of the hour
3395
@item @tab @code{VALUE(7)}: @tab The seconds of the minute
3396
@item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3397
@end multitable
3398
 
3399
@item @emph{Standard}:
3400
Fortran 95 and later
3401
 
3402
@item @emph{Class}:
3403
Subroutine
3404
 
3405
@item @emph{Syntax}:
3406
@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3407
 
3408
@item @emph{Arguments}:
3409
@multitable @columnfractions .15 .70
3410
@item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3411
or larger, and of default kind.
3412
@item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3413
or larger, and of default kind.
3414
@item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3415
or larger, and of default kind.
3416
@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3417
@end multitable
3418
 
3419
@item @emph{Return value}:
3420
None
3421
 
3422
@item @emph{Example}:
3423
@smallexample
3424
program test_time_and_date
3425
    character(8)  :: date
3426
    character(10) :: time
3427
    character(5)  :: zone
3428
    integer,dimension(8) :: values
3429
    ! using keyword arguments
3430
    call date_and_time(date,time,zone,values)
3431
    call date_and_time(DATE=date,ZONE=zone)
3432
    call date_and_time(TIME=time)
3433
    call date_and_time(VALUES=values)
3434
    print '(a,2x,a,2x,a)', date, time, zone
3435
    print '(8i5))', values
3436
end program test_time_and_date
3437
@end smallexample
3438
 
3439
@item @emph{See also}:
3440
@ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3441
@end table
3442
 
3443
 
3444
 
3445
@node DBLE
3446
@section @code{DBLE} --- Double conversion function
3447
@fnindex DBLE
3448
@cindex conversion, to real
3449
 
3450
@table @asis
3451
@item @emph{Description}:
3452
@code{DBLE(A)} Converts @var{A} to double precision real type.
3453
 
3454
@item @emph{Standard}:
3455
Fortran 77 and later
3456
 
3457
@item @emph{Class}:
3458
Elemental function
3459
 
3460
@item @emph{Syntax}:
3461
@code{RESULT = DBLE(A)}
3462
 
3463
@item @emph{Arguments}:
3464
@multitable @columnfractions .15 .70
3465
@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3466
or @code{COMPLEX}.
3467
@end multitable
3468
 
3469
@item @emph{Return value}:
3470
The return value is of type double precision real.
3471
 
3472
@item @emph{Example}:
3473
@smallexample
3474
program test_dble
3475
    real    :: x = 2.18
3476
    integer :: i = 5
3477
    complex :: z = (2.3,1.14)
3478
    print *, dble(x), dble(i), dble(z)
3479
end program test_dble
3480
@end smallexample
3481
 
3482
@item @emph{See also}:
3483
@ref{REAL}
3484
@end table
3485
 
3486
 
3487
 
3488
@node DCMPLX
3489
@section @code{DCMPLX} --- Double complex conversion function
3490
@fnindex DCMPLX
3491
@cindex complex numbers, conversion to
3492
@cindex conversion, to complex
3493
 
3494
@table @asis
3495
@item @emph{Description}:
3496
@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3497
converted to the real component.  If @var{Y} is present it is converted to the
3498
imaginary component.  If @var{Y} is not present then the imaginary component is
3499
set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3500
 
3501
@item @emph{Standard}:
3502
GNU extension
3503
 
3504
@item @emph{Class}:
3505
Elemental function
3506
 
3507
@item @emph{Syntax}:
3508
@code{RESULT = DCMPLX(X [, Y])}
3509
 
3510
@item @emph{Arguments}:
3511
@multitable @columnfractions .15 .70
3512
@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3513
or @code{COMPLEX}.
3514
@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3515
@code{INTEGER} or @code{REAL}.
3516
@end multitable
3517
 
3518
@item @emph{Return value}:
3519
The return value is of type @code{COMPLEX(8)}
3520
 
3521
@item @emph{Example}:
3522
@smallexample
3523
program test_dcmplx
3524
    integer :: i = 42
3525
    real :: x = 3.14
3526
    complex :: z
3527
    z = cmplx(i, x)
3528
    print *, dcmplx(i)
3529
    print *, dcmplx(x)
3530
    print *, dcmplx(z)
3531
    print *, dcmplx(x,i)
3532
end program test_dcmplx
3533
@end smallexample
3534
@end table
3535
 
3536
 
3537
@node DIGITS
3538
@section @code{DIGITS} --- Significant binary digits function
3539
@fnindex DIGITS
3540
@cindex model representation, significant digits
3541
 
3542
@table @asis
3543
@item @emph{Description}:
3544
@code{DIGITS(X)} returns the number of significant binary digits of the internal
3545
model representation of @var{X}.  For example, on a system using a 32-bit
3546
floating point representation, a default real number would likely return 24.
3547
 
3548
@item @emph{Standard}:
3549
Fortran 95 and later
3550
 
3551
@item @emph{Class}:
3552
Inquiry function
3553
 
3554
@item @emph{Syntax}:
3555
@code{RESULT = DIGITS(X)}
3556
 
3557
@item @emph{Arguments}:
3558
@multitable @columnfractions .15 .70
3559
@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3560
@end multitable
3561
 
3562
@item @emph{Return value}:
3563
The return value is of type @code{INTEGER}.
3564
 
3565
@item @emph{Example}:
3566
@smallexample
3567
program test_digits
3568
    integer :: i = 12345
3569
    real :: x = 3.143
3570
    real(8) :: y = 2.33
3571
    print *, digits(i)
3572
    print *, digits(x)
3573
    print *, digits(y)
3574
end program test_digits
3575
@end smallexample
3576
@end table
3577
 
3578
 
3579
 
3580
@node DIM
3581
@section @code{DIM} --- Positive difference
3582
@fnindex DIM
3583
@fnindex IDIM
3584
@fnindex DDIM
3585
@cindex positive difference
3586
 
3587
@table @asis
3588
@item @emph{Description}:
3589
@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3590
otherwise returns zero.
3591
 
3592
@item @emph{Standard}:
3593
Fortran 77 and later
3594
 
3595
@item @emph{Class}:
3596
Elemental function
3597
 
3598
@item @emph{Syntax}:
3599
@code{RESULT = DIM(X, Y)}
3600
 
3601
@item @emph{Arguments}:
3602
@multitable @columnfractions .15 .70
3603
@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3604
@item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3605
@end multitable
3606
 
3607
@item @emph{Return value}:
3608
The return value is of type @code{INTEGER} or @code{REAL}.
3609
 
3610
@item @emph{Example}:
3611
@smallexample
3612
program test_dim
3613
    integer :: i
3614
    real(8) :: x
3615
    i = dim(4, 15)
3616
    x = dim(4.345_8, 2.111_8)
3617
    print *, i
3618
    print *, x
3619
end program test_dim
3620
@end smallexample
3621
 
3622
@item @emph{Specific names}:
3623
@multitable @columnfractions .20 .20 .20 .25
3624
@item Name             @tab Argument               @tab Return type       @tab Standard
3625
@item @code{DIM(X,Y)}  @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3626
@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3627
@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3628
@end multitable
3629
@end table
3630
 
3631
 
3632
 
3633
@node DOT_PRODUCT
3634
@section @code{DOT_PRODUCT} --- Dot product function
3635
@fnindex DOT_PRODUCT
3636
@cindex dot product
3637
@cindex vector product
3638
@cindex product, vector
3639
 
3640
@table @asis
3641
@item @emph{Description}:
3642
@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3643
of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
3644
either numeric or logical and must be arrays of rank one and of equal size. If
3645
the vectors are @code{INTEGER} or @code{REAL}, the result is
3646
@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3647
is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3648
the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3649
 
3650
@item @emph{Standard}:
3651
Fortran 95 and later
3652
 
3653
@item @emph{Class}:
3654
Transformational function
3655
 
3656
@item @emph{Syntax}:
3657
@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3658
 
3659
@item @emph{Arguments}:
3660
@multitable @columnfractions .15 .70
3661
@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3662
@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.
3663
@end multitable
3664
 
3665
@item @emph{Return value}:
3666
If the arguments are numeric, the return value is a scalar of numeric type,
3667
@code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
3668
@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3669
 
3670
@item @emph{Example}:
3671
@smallexample
3672
program test_dot_prod
3673
    integer, dimension(3) :: a, b
3674
    a = (/ 1, 2, 3 /)
3675
    b = (/ 4, 5, 6 /)
3676
    print '(3i3)', a
3677
    print *
3678
    print '(3i3)', b
3679
    print *
3680
    print *, dot_product(a,b)
3681
end program test_dot_prod
3682
@end smallexample
3683
@end table
3684
 
3685
 
3686
 
3687
@node DPROD
3688
@section @code{DPROD} --- Double product function
3689
@fnindex DPROD
3690
@cindex product, double-precision
3691
 
3692
@table @asis
3693
@item @emph{Description}:
3694
@code{DPROD(X,Y)} returns the product @code{X*Y}.
3695
 
3696
@item @emph{Standard}:
3697
Fortran 77 and later
3698
 
3699
@item @emph{Class}:
3700
Elemental function
3701
 
3702
@item @emph{Syntax}:
3703
@code{RESULT = DPROD(X, Y)}
3704
 
3705
@item @emph{Arguments}:
3706
@multitable @columnfractions .15 .70
3707
@item @var{X} @tab The type shall be @code{REAL}.
3708
@item @var{Y} @tab The type shall be @code{REAL}.
3709
@end multitable
3710
 
3711
@item @emph{Return value}:
3712
The return value is of type @code{REAL(8)}.
3713
 
3714
@item @emph{Example}:
3715
@smallexample
3716
program test_dprod
3717
    real :: x = 5.2
3718
    real :: y = 2.3
3719
    real(8) :: d
3720
    d = dprod(x,y)
3721
    print *, d
3722
end program test_dprod
3723
@end smallexample
3724
 
3725
@item @emph{Specific names}:
3726
@multitable @columnfractions .20 .20 .20 .25
3727
@item Name              @tab Argument               @tab Return type       @tab Standard
3728
@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3729
@end multitable
3730
 
3731
@end table
3732
 
3733
 
3734
@node DREAL
3735
@section @code{DREAL} --- Double real part function
3736
@fnindex DREAL
3737
@cindex complex numbers, real part
3738
 
3739
@table @asis
3740
@item @emph{Description}:
3741
@code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3742
 
3743
@item @emph{Standard}:
3744
GNU extension
3745
 
3746
@item @emph{Class}:
3747
Elemental function
3748
 
3749
@item @emph{Syntax}:
3750
@code{RESULT = DREAL(A)}
3751
 
3752
@item @emph{Arguments}:
3753
@multitable @columnfractions .15 .70
3754
@item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3755
@end multitable
3756
 
3757
@item @emph{Return value}:
3758
The return value is of type @code{REAL(8)}.
3759
 
3760
@item @emph{Example}:
3761
@smallexample
3762
program test_dreal
3763
    complex(8) :: z = (1.3_8,7.2_8)
3764
    print *, dreal(z)
3765
end program test_dreal
3766
@end smallexample
3767
 
3768
@item @emph{See also}:
3769
@ref{AIMAG}
3770
 
3771
@end table
3772
 
3773
 
3774
 
3775
@node DSHIFTL
3776
@section @code{DSHIFTL} --- Combined left shift
3777
@fnindex DSHIFTL
3778
@cindex left shift, combined
3779
@cindex shift, left
3780
 
3781
@table @asis
3782
@item @emph{Description}:
3783
@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3784
rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3785
bits of @var{J}, and the remaining bits are the rightmost bits of
3786
@var{I}.
3787
 
3788
@item @emph{Standard}:
3789
Fortran 2008 and later
3790
 
3791
@item @emph{Class}:
3792
Elemental function
3793
 
3794
@item @emph{Syntax}:
3795
@code{RESULT = DSHIFTL(I, J, SHIFT)}
3796
 
3797
@item @emph{Arguments}:
3798
@multitable @columnfractions .15 .70
3799
@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3800
@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3801
If both @var{I} and @var{J} have integer type, then they shall have
3802
the same kind type parameter. @var{I} and @var{J} shall not both be
3803
BOZ constants.
3804
@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3805
be nonnegative.  If @var{I} is not a BOZ constant, then @var{SHIFT}
3806
shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3807
@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3808
@end multitable
3809
 
3810
@item @emph{Return value}:
3811
If either @var{I} or @var{J} is a BOZ constant, it is first converted
3812
as if by the intrinsic function @code{INT} to an integer type with the
3813
kind type parameter of the other.
3814
 
3815
@item @emph{See also}:
3816
@ref{DSHIFTR}
3817
@end table
3818
 
3819
 
3820
@node DSHIFTR
3821
@section @code{DSHIFTR} --- Combined right shift
3822
@fnindex DSHIFTR
3823
@cindex right shift, combined
3824
@cindex shift, right
3825
 
3826
@table @asis
3827
@item @emph{Description}:
3828
@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3829
leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3830
bits of @var{I}, and the remaining bits are the leftmost bits of
3831
@var{J}.
3832
 
3833
@item @emph{Standard}:
3834
Fortran 2008 and later
3835
 
3836
@item @emph{Class}:
3837
Elemental function
3838
 
3839
@item @emph{Syntax}:
3840
@code{RESULT = DSHIFTR(I, J, SHIFT)}
3841
 
3842
@item @emph{Arguments}:
3843
@multitable @columnfractions .15 .70
3844
@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3845
@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3846
If both @var{I} and @var{J} have integer type, then they shall have
3847
the same kind type parameter. @var{I} and @var{J} shall not both be
3848
BOZ constants.
3849
@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3850
be nonnegative.  If @var{I} is not a BOZ constant, then @var{SHIFT}
3851
shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3852
@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3853
@end multitable
3854
 
3855
@item @emph{Return value}:
3856
If either @var{I} or @var{J} is a BOZ constant, it is first converted
3857
as if by the intrinsic function @code{INT} to an integer type with the
3858
kind type parameter of the other.
3859
 
3860
@item @emph{See also}:
3861
@ref{DSHIFTL}
3862
@end table
3863
 
3864
 
3865
@node DTIME
3866
@section @code{DTIME} --- Execution time subroutine (or function)
3867
@fnindex DTIME
3868
@cindex time, elapsed
3869
@cindex elapsed time
3870
 
3871
@table @asis
3872
@item @emph{Description}:
3873
@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3874
since the start of the process's execution in @var{TIME}.  @var{VALUES}
3875
returns the user and system components of this time in @code{VALUES(1)} and
3876
@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3877
VALUES(2)}.
3878
 
3879
Subsequent invocations of @code{DTIME} return values accumulated since the
3880
previous invocation.
3881
 
3882
On some systems, the underlying timings are represented using types with
3883
sufficiently small limits that overflows (wrap around) are possible, such as
3884
32-bit types. Therefore, the values returned by this intrinsic might be, or
3885
become, negative, or numerically less than previous values, during a single
3886
run of the compiled program.
3887
 
3888
Please note, that this implementation is thread safe if used within OpenMP
3889
directives, i.e., its state will be consistent while called from multiple
3890
threads. However, if @code{DTIME} is called from multiple threads, the result
3891
is still the time since the last invocation. This may not give the intended
3892
results. If possible, use @code{CPU_TIME} instead.
3893
 
3894
This intrinsic is provided in both subroutine and function forms; however,
3895
only one form can be used in any given program unit.
3896
 
3897
@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3898
 
3899
@multitable @columnfractions .15 .30 .40
3900
@item @tab @code{VALUES(1)}: @tab User time in seconds.
3901
@item @tab @code{VALUES(2)}: @tab System time in seconds.
3902
@item @tab @code{TIME}: @tab Run time since start in seconds.
3903
@end multitable
3904
 
3905
@item @emph{Standard}:
3906
GNU extension
3907
 
3908
@item @emph{Class}:
3909
Subroutine, function
3910
 
3911
@item @emph{Syntax}:
3912
@multitable @columnfractions .80
3913
@item @code{CALL DTIME(VALUES, TIME)}.
3914
@item @code{TIME = DTIME(VALUES)}, (not recommended).
3915
@end multitable
3916
 
3917
@item @emph{Arguments}:
3918
@multitable @columnfractions .15 .70
3919
@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3920
@item @var{TIME}@tab The type shall be @code{REAL(4)}.
3921
@end multitable
3922
 
3923
@item @emph{Return value}:
3924
Elapsed time in seconds since the last invocation or since the start of program
3925
execution if not called before.
3926
 
3927
@item @emph{Example}:
3928
@smallexample
3929
program test_dtime
3930
    integer(8) :: i, j
3931
    real, dimension(2) :: tarray
3932
    real :: result
3933
    call dtime(tarray, result)
3934
    print *, result
3935
    print *, tarray(1)
3936
    print *, tarray(2)
3937
    do i=1,100000000    ! Just a delay
3938
        j = i * i - i
3939
    end do
3940
    call dtime(tarray, result)
3941
    print *, result
3942
    print *, tarray(1)
3943
    print *, tarray(2)
3944
end program test_dtime
3945
@end smallexample
3946
 
3947
@item @emph{See also}:
3948
@ref{CPU_TIME}
3949
 
3950
@end table
3951
 
3952
 
3953
 
3954
@node EOSHIFT
3955
@section @code{EOSHIFT} --- End-off shift elements of an array
3956
@fnindex EOSHIFT
3957
@cindex array, shift
3958
 
3959
@table @asis
3960
@item @emph{Description}:
3961
@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3962
elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3963
omitted it is taken to be @code{1}.  @var{DIM} is a scalar of type
3964
@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3965
rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3966
@var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3967
then all complete rank one sections of @var{ARRAY} along the given dimension are
3968
shifted.  Elements shifted out one end of each rank one section are dropped.  If
3969
@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3970
is copied back in the other end.  If @var{BOUNDARY} is not present then the
3971
following are copied in depending on the type of @var{ARRAY}.
3972
 
3973
@multitable @columnfractions .15 .80
3974
@item @emph{Array Type} @tab @emph{Boundary Value}
3975
@item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3976
@item Logical  @tab @code{.FALSE.}.
3977
@item Character(@var{len}) @tab @var{len} blanks.
3978
@end multitable
3979
 
3980
@item @emph{Standard}:
3981
Fortran 95 and later
3982
 
3983
@item @emph{Class}:
3984
Transformational function
3985
 
3986
@item @emph{Syntax}:
3987
@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3988
 
3989
@item @emph{Arguments}:
3990
@multitable @columnfractions .15 .70
3991
@item @var{ARRAY}  @tab May be any type, not scalar.
3992
@item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3993
@item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3994
@item @var{DIM}    @tab The type shall be @code{INTEGER}.
3995
@end multitable
3996
 
3997
@item @emph{Return value}:
3998
Returns an array of same type and rank as the @var{ARRAY} argument.
3999
 
4000
@item @emph{Example}:
4001
@smallexample
4002
program test_eoshift
4003
    integer, dimension(3,3) :: a
4004
    a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4005
    print '(3i3)', a(1,:)
4006
    print '(3i3)', a(2,:)
4007
    print '(3i3)', a(3,:)
4008
    a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4009
    print *
4010
    print '(3i3)', a(1,:)
4011
    print '(3i3)', a(2,:)
4012
    print '(3i3)', a(3,:)
4013
end program test_eoshift
4014
@end smallexample
4015
@end table
4016
 
4017
 
4018
 
4019
@node EPSILON
4020
@section @code{EPSILON} --- Epsilon function
4021
@fnindex EPSILON
4022
@cindex model representation, epsilon
4023
 
4024
@table @asis
4025
@item @emph{Description}:
4026
@code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4027
as @var{X} such that @math{1 + E > 1}.
4028
 
4029
@item @emph{Standard}:
4030
Fortran 95 and later
4031
 
4032
@item @emph{Class}:
4033
Inquiry function
4034
 
4035
@item @emph{Syntax}:
4036
@code{RESULT = EPSILON(X)}
4037
 
4038
@item @emph{Arguments}:
4039
@multitable @columnfractions .15 .70
4040
@item @var{X} @tab The type shall be @code{REAL}.
4041
@end multitable
4042
 
4043
@item @emph{Return value}:
4044
The return value is of same type as the argument.
4045
 
4046
@item @emph{Example}:
4047
@smallexample
4048
program test_epsilon
4049
    real :: x = 3.143
4050
    real(8) :: y = 2.33
4051
    print *, EPSILON(x)
4052
    print *, EPSILON(y)
4053
end program test_epsilon
4054
@end smallexample
4055
@end table
4056
 
4057
 
4058
 
4059
@node ERF
4060
@section @code{ERF} --- Error function
4061
@fnindex ERF
4062
@cindex error function
4063
 
4064
@table @asis
4065
@item @emph{Description}:
4066
@code{ERF(X)} computes the error function of @var{X}.
4067
 
4068
@item @emph{Standard}:
4069
Fortran 2008 and later
4070
 
4071
@item @emph{Class}:
4072
Elemental function
4073
 
4074
@item @emph{Syntax}:
4075
@code{RESULT = ERF(X)}
4076
 
4077
@item @emph{Arguments}:
4078
@multitable @columnfractions .15 .70
4079
@item @var{X} @tab The type shall be @code{REAL}.
4080
@end multitable
4081
 
4082
@item @emph{Return value}:
4083
The return value is of type @code{REAL}, of the same kind as
4084
@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4085
 
4086
@item @emph{Example}:
4087
@smallexample
4088
program test_erf
4089
  real(8) :: x = 0.17_8
4090
  x = erf(x)
4091
end program test_erf
4092
@end smallexample
4093
 
4094
@item @emph{Specific names}:
4095
@multitable @columnfractions .20 .20 .20 .25
4096
@item Name            @tab Argument          @tab Return type       @tab Standard
4097
@item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
4098
@end multitable
4099
@end table
4100
 
4101
 
4102
 
4103
@node ERFC
4104
@section @code{ERFC} --- Error function
4105
@fnindex ERFC
4106
@cindex error function, complementary
4107
 
4108
@table @asis
4109
@item @emph{Description}:
4110
@code{ERFC(X)} computes the complementary error function of @var{X}.
4111
 
4112
@item @emph{Standard}:
4113
Fortran 2008 and later
4114
 
4115
@item @emph{Class}:
4116
Elemental function
4117
 
4118
@item @emph{Syntax}:
4119
@code{RESULT = ERFC(X)}
4120
 
4121
@item @emph{Arguments}:
4122
@multitable @columnfractions .15 .70
4123
@item @var{X} @tab The type shall be @code{REAL}.
4124
@end multitable
4125
 
4126
@item @emph{Return value}:
4127
The return value is of type @code{REAL} and of the same kind as @var{X}.
4128
It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4129
 
4130
@item @emph{Example}:
4131
@smallexample
4132
program test_erfc
4133
  real(8) :: x = 0.17_8
4134
  x = erfc(x)
4135
end program test_erfc
4136
@end smallexample
4137
 
4138
@item @emph{Specific names}:
4139
@multitable @columnfractions .20 .20 .20 .25
4140
@item Name            @tab Argument          @tab Return type       @tab Standard
4141
@item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
4142
@end multitable
4143
@end table
4144
 
4145
 
4146
 
4147
@node ERFC_SCALED
4148
@section @code{ERFC_SCALED} --- Error function
4149
@fnindex ERFC_SCALED
4150
@cindex error function, complementary, exponentially-scaled
4151
 
4152
@table @asis
4153
@item @emph{Description}:
4154
@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4155
error function of @var{X}.
4156
 
4157
@item @emph{Standard}:
4158
Fortran 2008 and later
4159
 
4160
@item @emph{Class}:
4161
Elemental function
4162
 
4163
@item @emph{Syntax}:
4164
@code{RESULT = ERFC_SCALED(X)}
4165
 
4166
@item @emph{Arguments}:
4167
@multitable @columnfractions .15 .70
4168
@item @var{X} @tab The type shall be @code{REAL}.
4169
@end multitable
4170
 
4171
@item @emph{Return value}:
4172
The return value is of type @code{REAL} and of the same kind as @var{X}.
4173
 
4174
@item @emph{Example}:
4175
@smallexample
4176
program test_erfc_scaled
4177
  real(8) :: x = 0.17_8
4178
  x = erfc_scaled(x)
4179
end program test_erfc_scaled
4180
@end smallexample
4181
@end table
4182
 
4183
 
4184
 
4185
@node ETIME
4186
@section @code{ETIME} --- Execution time subroutine (or function)
4187
@fnindex ETIME
4188
@cindex time, elapsed
4189
 
4190
@table @asis
4191
@item @emph{Description}:
4192
@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4193
since the start of the process's execution in @var{TIME}.  @var{VALUES}
4194
returns the user and system components of this time in @code{VALUES(1)} and
4195
@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4196
 
4197
On some systems, the underlying timings are represented using types with
4198
sufficiently small limits that overflows (wrap around) are possible, such as
4199
32-bit types. Therefore, the values returned by this intrinsic might be, or
4200
become, negative, or numerically less than previous values, during a single
4201
run of the compiled program.
4202
 
4203
This intrinsic is provided in both subroutine and function forms; however,
4204
only one form can be used in any given program unit.
4205
 
4206
@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4207
 
4208
@multitable @columnfractions .15 .30 .60
4209
@item @tab @code{VALUES(1)}: @tab User time in seconds.
4210
@item @tab @code{VALUES(2)}: @tab System time in seconds.
4211
@item @tab @code{TIME}: @tab Run time since start in seconds.
4212
@end multitable
4213
 
4214
@item @emph{Standard}:
4215
GNU extension
4216
 
4217
@item @emph{Class}:
4218
Subroutine, function
4219
 
4220
@item @emph{Syntax}:
4221
@multitable @columnfractions .80
4222
@item @code{CALL ETIME(VALUES, TIME)}.
4223
@item @code{TIME = ETIME(VALUES)}, (not recommended).
4224
@end multitable
4225
 
4226
@item @emph{Arguments}:
4227
@multitable @columnfractions .15 .70
4228
@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4229
@item @var{TIME}@tab The type shall be @code{REAL(4)}.
4230
@end multitable
4231
 
4232
@item @emph{Return value}:
4233
Elapsed time in seconds since the start of program execution.
4234
 
4235
@item @emph{Example}:
4236
@smallexample
4237
program test_etime
4238
    integer(8) :: i, j
4239
    real, dimension(2) :: tarray
4240
    real :: result
4241
    call ETIME(tarray, result)
4242
    print *, result
4243
    print *, tarray(1)
4244
    print *, tarray(2)
4245
    do i=1,100000000    ! Just a delay
4246
        j = i * i - i
4247
    end do
4248
    call ETIME(tarray, result)
4249
    print *, result
4250
    print *, tarray(1)
4251
    print *, tarray(2)
4252
end program test_etime
4253
@end smallexample
4254
 
4255
@item @emph{See also}:
4256
@ref{CPU_TIME}
4257
 
4258
@end table
4259
 
4260
 
4261
 
4262
@node EXECUTE_COMMAND_LINE
4263
@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4264
@fnindex EXECUTE_COMMAND_LINE
4265
@cindex system, system call
4266
@cindex command line
4267
 
4268
@table @asis
4269
@item @emph{Description}:
4270
@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4271
asynchronously.
4272
 
4273
The @code{COMMAND} argument is passed to the shell and executed, using
4274
the C library's @code{system} call.  (The shell is @code{sh} on Unix
4275
systems, and @code{cmd.exe} on Windows.)  If @code{WAIT} is present
4276
and has the value false, the execution of the command is asynchronous
4277
if the system supports it; otherwise, the command is executed
4278
synchronously.
4279
 
4280
The three last arguments allow the user to get status information.  After
4281
synchronous execution, @code{EXITSTAT} contains the integer exit code of
4282
the command, as returned by @code{system}.  @code{CMDSTAT} is set to zero
4283
if the command line was executed (whatever its exit status was).
4284
@code{CMDMSG} is assigned an error message if an error has occurred.
4285
 
4286
Note that the @code{system} function need not be thread-safe. It is
4287
the responsibility of the user to ensure that @code{system} is not
4288
called concurrently.
4289
 
4290
@item @emph{Standard}:
4291
Fortran 2008 and later
4292
 
4293
@item @emph{Class}:
4294
Subroutine
4295
 
4296
@item @emph{Syntax}:
4297
@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4298
 
4299
@item @emph{Arguments}:
4300
@multitable @columnfractions .15 .70
4301
@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4302
@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4303
@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4304
default kind.
4305
@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4306
default kind.
4307
@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4308
default kind.
4309
@end multitable
4310
 
4311
@item @emph{Example}:
4312
@smallexample
4313
program test_exec
4314
  integer :: i
4315
 
4316
  call execute_command_line ("external_prog.exe", exitstat=i)
4317
  print *, "Exit status of external_prog.exe was ", i
4318
 
4319
  call execute_command_line ("reindex_files.exe", wait=.false.)
4320
  print *, "Now reindexing files in the background"
4321
 
4322
end program test_exec
4323
@end smallexample
4324
 
4325
 
4326
@item @emph{Note}:
4327
 
4328
Because this intrinsic is implemented in terms of the @code{system}
4329
function call, its behavior with respect to signaling is processor
4330
dependent. In particular, on POSIX-compliant systems, the SIGINT and
4331
SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4332
such, if the parent process is terminated, the child process might not be
4333
terminated alongside.
4334
 
4335
 
4336
@item @emph{See also}:
4337
@ref{SYSTEM}
4338
@end table
4339
 
4340
 
4341
 
4342
@node EXIT
4343
@section @code{EXIT} --- Exit the program with status.
4344
@fnindex EXIT
4345
@cindex program termination
4346
@cindex terminate program
4347
 
4348
@table @asis
4349
@item @emph{Description}:
4350
@code{EXIT} causes immediate termination of the program with status.  If status
4351
is omitted it returns the canonical @emph{success} for the system.  All Fortran
4352
I/O units are closed.
4353
 
4354
@item @emph{Standard}:
4355
GNU extension
4356
 
4357
@item @emph{Class}:
4358
Subroutine
4359
 
4360
@item @emph{Syntax}:
4361
@code{CALL EXIT([STATUS])}
4362
 
4363
@item @emph{Arguments}:
4364
@multitable @columnfractions .15 .70
4365
@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4366
@end multitable
4367
 
4368
@item @emph{Return value}:
4369
@code{STATUS} is passed to the parent process on exit.
4370
 
4371
@item @emph{Example}:
4372
@smallexample
4373
program test_exit
4374
  integer :: STATUS = 0
4375
  print *, 'This program is going to exit.'
4376
  call EXIT(STATUS)
4377
end program test_exit
4378
@end smallexample
4379
 
4380
@item @emph{See also}:
4381
@ref{ABORT}, @ref{KILL}
4382
@end table
4383
 
4384
 
4385
 
4386
@node EXP
4387
@section @code{EXP} --- Exponential function
4388
@fnindex EXP
4389
@fnindex DEXP
4390
@fnindex CEXP
4391
@fnindex ZEXP
4392
@fnindex CDEXP
4393
@cindex exponential function
4394
@cindex logarithm function, inverse
4395
 
4396
@table @asis
4397
@item @emph{Description}:
4398
@code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4399
 
4400
@item @emph{Standard}:
4401
Fortran 77 and later, has overloads that are GNU extensions
4402
 
4403
@item @emph{Class}:
4404
Elemental function
4405
 
4406
@item @emph{Syntax}:
4407
@code{RESULT = EXP(X)}
4408
 
4409
@item @emph{Arguments}:
4410
@multitable @columnfractions .15 .70
4411
@item @var{X} @tab The type shall be @code{REAL} or
4412
@code{COMPLEX}.
4413
@end multitable
4414
 
4415
@item @emph{Return value}:
4416
The return value has same type and kind as @var{X}.
4417
 
4418
@item @emph{Example}:
4419
@smallexample
4420
program test_exp
4421
  real :: x = 1.0
4422
  x = exp(x)
4423
end program test_exp
4424
@end smallexample
4425
 
4426
@item @emph{Specific names}:
4427
@multitable @columnfractions .20 .20 .20 .25
4428
@item Name            @tab Argument             @tab Return type         @tab Standard
4429
@item @code{EXP(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}      @tab Fortran 77 and later
4430
@item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
4431
@item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
4432
@item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4433
@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4434
@end multitable
4435
@end table
4436
 
4437
 
4438
 
4439
@node EXPONENT
4440
@section @code{EXPONENT} --- Exponent function
4441
@fnindex EXPONENT
4442
@cindex real number, exponent
4443
@cindex floating point, exponent
4444
 
4445
@table @asis
4446
@item @emph{Description}:
4447
@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4448
is zero the value returned is zero.
4449
 
4450
@item @emph{Standard}:
4451
Fortran 95 and later
4452
 
4453
@item @emph{Class}:
4454
Elemental function
4455
 
4456
@item @emph{Syntax}:
4457
@code{RESULT = EXPONENT(X)}
4458
 
4459
@item @emph{Arguments}:
4460
@multitable @columnfractions .15 .70
4461
@item @var{X} @tab The type shall be @code{REAL}.
4462
@end multitable
4463
 
4464
@item @emph{Return value}:
4465
The return value is of type default @code{INTEGER}.
4466
 
4467
@item @emph{Example}:
4468
@smallexample
4469
program test_exponent
4470
  real :: x = 1.0
4471
  integer :: i
4472
  i = exponent(x)
4473
  print *, i
4474
  print *, exponent(0.0)
4475
end program test_exponent
4476
@end smallexample
4477
@end table
4478
 
4479
 
4480
 
4481
@node EXTENDS_TYPE_OF
4482
@section @code{EXTENDS_TYPE_OF} ---  Query dynamic type for extension
4483
@fnindex EXTENDS_TYPE_OF
4484
 
4485
@table @asis
4486
@item @emph{Description}:
4487
Query dynamic type for extension.
4488
 
4489
@item @emph{Standard}:
4490
Fortran 2003 and later
4491
 
4492
@item @emph{Class}:
4493
Inquiry function
4494
 
4495
@item @emph{Syntax}:
4496
@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4497
 
4498
@item @emph{Arguments}:
4499
@multitable @columnfractions .15 .70
4500
@item @var{A} @tab Shall be an object of extensible declared type or
4501
unlimited polymorphic.
4502
@item @var{MOLD} @tab Shall be an object of extensible declared type or
4503
unlimited polymorphic.
4504
@end multitable
4505
 
4506
@item @emph{Return value}:
4507
The return value is a scalar of type default logical. It is true if and only if
4508
the dynamic type of A is an extension type of the dynamic type of MOLD.
4509
 
4510
 
4511
@item @emph{See also}:
4512
@ref{SAME_TYPE_AS}
4513
@end table
4514
 
4515
 
4516
 
4517
@node FDATE
4518
@section @code{FDATE} --- Get the current time as a string
4519
@fnindex FDATE
4520
@cindex time, current
4521
@cindex current time
4522
@cindex date, current
4523
@cindex current date
4524
 
4525
@table @asis
4526
@item @emph{Description}:
4527
@code{FDATE(DATE)} returns the current date (using the same format as
4528
@code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4529
TIME())}.
4530
 
4531
This intrinsic is provided in both subroutine and function forms; however,
4532
only one form can be used in any given program unit.
4533
 
4534
@item @emph{Standard}:
4535
GNU extension
4536
 
4537
@item @emph{Class}:
4538
Subroutine, function
4539
 
4540
@item @emph{Syntax}:
4541
@multitable @columnfractions .80
4542
@item @code{CALL FDATE(DATE)}.
4543
@item @code{DATE = FDATE()}.
4544
@end multitable
4545
 
4546
@item @emph{Arguments}:
4547
@multitable @columnfractions .15 .70
4548
@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4549
default kind. It is an @code{INTENT(OUT)} argument.  If the length of
4550
this variable is too short for the date and time string to fit
4551
completely, it will be blank on procedure return.
4552
@end multitable
4553
 
4554
@item @emph{Return value}:
4555
The current date and time as a string.
4556
 
4557
@item @emph{Example}:
4558
@smallexample
4559
program test_fdate
4560
    integer(8) :: i, j
4561
    character(len=30) :: date
4562
    call fdate(date)
4563
    print *, 'Program started on ', date
4564
    do i = 1, 100000000 ! Just a delay
4565
        j = i * i - i
4566
    end do
4567
    call fdate(date)
4568
    print *, 'Program ended on ', date
4569
end program test_fdate
4570
@end smallexample
4571
 
4572
@item @emph{See also}:
4573
@ref{DATE_AND_TIME}, @ref{CTIME}
4574
@end table
4575
 
4576
 
4577
@node FGET
4578
@section @code{FGET} --- Read a single character in stream mode from stdin
4579
@fnindex FGET
4580
@cindex read character, stream mode
4581
@cindex stream mode, read character
4582
@cindex file operation, read character
4583
 
4584
@table @asis
4585
@item @emph{Description}:
4586
Read a single character in stream mode from stdin by bypassing normal
4587
formatted output. Stream I/O should not be mixed with normal record-oriented
4588
(formatted or unformatted) I/O on the same unit; the results are unpredictable.
4589
 
4590
This intrinsic is provided in both subroutine and function forms; however,
4591
only one form can be used in any given program unit.
4592
 
4593
Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4594
@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4595
Programmers should consider the use of new stream IO feature in new code
4596
for future portability. See also @ref{Fortran 2003 status}.
4597
 
4598
@item @emph{Standard}:
4599
GNU extension
4600
 
4601
@item @emph{Class}:
4602
Subroutine, function
4603
 
4604
@item @emph{Syntax}:
4605
@multitable @columnfractions .80
4606
@item @code{CALL FGET(C [, STATUS])}
4607
@item @code{STATUS = FGET(C)}
4608
@end multitable
4609
 
4610
@item @emph{Arguments}:
4611
@multitable @columnfractions .15 .70
4612
@item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4613
kind.
4614
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4615
Returns 0 on success, -1 on end-of-file, and a system specific positive
4616
error code otherwise.
4617
@end multitable
4618
 
4619
@item @emph{Example}:
4620
@smallexample
4621
PROGRAM test_fget
4622
  INTEGER, PARAMETER :: strlen = 100
4623
  INTEGER :: status, i = 1
4624
  CHARACTER(len=strlen) :: str = ""
4625
 
4626
  WRITE (*,*) 'Enter text:'
4627
  DO
4628
    CALL fget(str(i:i), status)
4629
    if (status /= 0 .OR. i > strlen) exit
4630
    i = i + 1
4631
  END DO
4632
  WRITE (*,*) TRIM(str)
4633
END PROGRAM
4634
@end smallexample
4635
 
4636
@item @emph{See also}:
4637
@ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4638
@end table
4639
 
4640
 
4641
 
4642
@node FGETC
4643
@section @code{FGETC} --- Read a single character in stream mode
4644
@fnindex FGETC
4645
@cindex read character, stream mode
4646
@cindex stream mode, read character
4647
@cindex file operation, read character
4648
 
4649
@table @asis
4650
@item @emph{Description}:
4651
Read a single character in stream mode by bypassing normal formatted output.
4652
Stream I/O should not be mixed with normal record-oriented (formatted or
4653
unformatted) I/O on the same unit; the results are unpredictable.
4654
 
4655
This intrinsic is provided in both subroutine and function forms; however,
4656
only one form can be used in any given program unit.
4657
 
4658
Note that the @code{FGET} intrinsic is provided for backwards compatibility
4659
with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4660
Programmers should consider the use of new stream IO feature in new code
4661
for future portability. See also @ref{Fortran 2003 status}.
4662
 
4663
@item @emph{Standard}:
4664
GNU extension
4665
 
4666
@item @emph{Class}:
4667
Subroutine, function
4668
 
4669
@item @emph{Syntax}:
4670
@multitable @columnfractions .80
4671
@item @code{CALL FGETC(UNIT, C [, STATUS])}
4672
@item @code{STATUS = FGETC(UNIT, C)}
4673
@end multitable
4674
 
4675
@item @emph{Arguments}:
4676
@multitable @columnfractions .15 .70
4677
@item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4678
@item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4679
kind.
4680
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4681
Returns 0 on success, -1 on end-of-file and a system specific positive
4682
error code otherwise.
4683
@end multitable
4684
 
4685
@item @emph{Example}:
4686
@smallexample
4687
PROGRAM test_fgetc
4688
  INTEGER :: fd = 42, status
4689
  CHARACTER :: c
4690
 
4691
  OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4692
  DO
4693
    CALL fgetc(fd, c, status)
4694
    IF (status /= 0) EXIT
4695
    call fput(c)
4696
  END DO
4697
  CLOSE(UNIT=fd)
4698
END PROGRAM
4699
@end smallexample
4700
 
4701
@item @emph{See also}:
4702
@ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4703
@end table
4704
 
4705
 
4706
 
4707
@node FLOOR
4708
@section @code{FLOOR} --- Integer floor function
4709
@fnindex FLOOR
4710
@cindex floor
4711
@cindex rounding, floor
4712
 
4713
@table @asis
4714
@item @emph{Description}:
4715
@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4716
 
4717
@item @emph{Standard}:
4718
Fortran 95 and later
4719
 
4720
@item @emph{Class}:
4721
Elemental function
4722
 
4723
@item @emph{Syntax}:
4724
@code{RESULT = FLOOR(A [, KIND])}
4725
 
4726
@item @emph{Arguments}:
4727
@multitable @columnfractions .15 .70
4728
@item @var{A} @tab The type shall be @code{REAL}.
4729
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4730
expression indicating the kind parameter of the result.
4731
@end multitable
4732
 
4733
@item @emph{Return value}:
4734
The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4735
and of default-kind @code{INTEGER} otherwise.
4736
 
4737
@item @emph{Example}:
4738
@smallexample
4739
program test_floor
4740
    real :: x = 63.29
4741
    real :: y = -63.59
4742
    print *, floor(x) ! returns 63
4743
    print *, floor(y) ! returns -64
4744
end program test_floor
4745
@end smallexample
4746
 
4747
@item @emph{See also}:
4748
@ref{CEILING}, @ref{NINT}
4749
 
4750
@end table
4751
 
4752
 
4753
 
4754
@node FLUSH
4755
@section @code{FLUSH} --- Flush I/O unit(s)
4756
@fnindex FLUSH
4757
@cindex file operation, flush
4758
 
4759
@table @asis
4760
@item @emph{Description}:
4761
Flushes Fortran unit(s) currently open for output. Without the optional
4762
argument, all units are flushed, otherwise just the unit specified.
4763
 
4764
@item @emph{Standard}:
4765
GNU extension
4766
 
4767
@item @emph{Class}:
4768
Subroutine
4769
 
4770
@item @emph{Syntax}:
4771
@code{CALL FLUSH(UNIT)}
4772
 
4773
@item @emph{Arguments}:
4774
@multitable @columnfractions .15 .70
4775
@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4776
@end multitable
4777
 
4778
@item @emph{Note}:
4779
Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4780
statement that should be preferred over the @code{FLUSH} intrinsic.
4781
 
4782
The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4783
have identical effect: they flush the runtime library's I/O buffer so
4784
that the data becomes visible to other processes. This does not guarantee
4785
that the data is committed to disk.
4786
 
4787
On POSIX systems, you can request that all data is transferred  to  the
4788
storage device by calling the @code{fsync} function, with the POSIX file
4789
descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4790
@code{FNUM}). The following example shows how:
4791
 
4792
@smallexample
4793
  ! Declare the interface for POSIX fsync function
4794
  interface
4795
    function fsync (fd) bind(c,name="fsync")
4796
    use iso_c_binding, only: c_int
4797
      integer(c_int), value :: fd
4798
      integer(c_int) :: fsync
4799
    end function fsync
4800
  end interface
4801
 
4802
  ! Variable declaration
4803
  integer :: ret
4804
 
4805
  ! Opening unit 10
4806
  open (10,file="foo")
4807
 
4808
  ! ...
4809
  ! Perform I/O on unit 10
4810
  ! ...
4811
 
4812
  ! Flush and sync
4813
  flush(10)
4814
  ret = fsync(fnum(10))
4815
 
4816
  ! Handle possible error
4817
  if (ret /= 0) stop "Error calling FSYNC"
4818
@end smallexample
4819
 
4820
@end table
4821
 
4822
 
4823
 
4824
@node FNUM
4825
@section @code{FNUM} --- File number function
4826
@fnindex FNUM
4827
@cindex file operation, file number
4828
 
4829
@table @asis
4830
@item @emph{Description}:
4831
@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4832
open Fortran I/O unit @code{UNIT}.
4833
 
4834
@item @emph{Standard}:
4835
GNU extension
4836
 
4837
@item @emph{Class}:
4838
Function
4839
 
4840
@item @emph{Syntax}:
4841
@code{RESULT = FNUM(UNIT)}
4842
 
4843
@item @emph{Arguments}:
4844
@multitable @columnfractions .15 .70
4845
@item @var{UNIT} @tab The type shall be @code{INTEGER}.
4846
@end multitable
4847
 
4848
@item @emph{Return value}:
4849
The return value is of type @code{INTEGER}
4850
 
4851
@item @emph{Example}:
4852
@smallexample
4853
program test_fnum
4854
  integer :: i
4855
  open (unit=10, status = "scratch")
4856
  i = fnum(10)
4857
  print *, i
4858
  close (10)
4859
end program test_fnum
4860
@end smallexample
4861
@end table
4862
 
4863
 
4864
 
4865
@node FPUT
4866
@section @code{FPUT} --- Write a single character in stream mode to stdout
4867
@fnindex FPUT
4868
@cindex write character, stream mode
4869
@cindex stream mode, write character
4870
@cindex file operation, write character
4871
 
4872
@table @asis
4873
@item @emph{Description}:
4874
Write a single character in stream mode to stdout by bypassing normal
4875
formatted output. Stream I/O should not be mixed with normal record-oriented
4876
(formatted or unformatted) I/O on the same unit; the results are unpredictable.
4877
 
4878
This intrinsic is provided in both subroutine and function forms; however,
4879
only one form can be used in any given program unit.
4880
 
4881
Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4882
@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4883
Programmers should consider the use of new stream IO feature in new code
4884
for future portability. See also @ref{Fortran 2003 status}.
4885
 
4886
@item @emph{Standard}:
4887
GNU extension
4888
 
4889
@item @emph{Class}:
4890
Subroutine, function
4891
 
4892
@item @emph{Syntax}:
4893
@multitable @columnfractions .80
4894
@item @code{CALL FPUT(C [, STATUS])}
4895
@item @code{STATUS = FPUT(C)}
4896
@end multitable
4897
 
4898
@item @emph{Arguments}:
4899
@multitable @columnfractions .15 .70
4900
@item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4901
kind.
4902
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4903
Returns 0 on success, -1 on end-of-file and a system specific positive
4904
error code otherwise.
4905
@end multitable
4906
 
4907
@item @emph{Example}:
4908
@smallexample
4909
PROGRAM test_fput
4910
  CHARACTER(len=10) :: str = "gfortran"
4911
  INTEGER :: i
4912
  DO i = 1, len_trim(str)
4913
    CALL fput(str(i:i))
4914
  END DO
4915
END PROGRAM
4916
@end smallexample
4917
 
4918
@item @emph{See also}:
4919
@ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4920
@end table
4921
 
4922
 
4923
 
4924
@node FPUTC
4925
@section @code{FPUTC} --- Write a single character in stream mode
4926
@fnindex FPUTC
4927
@cindex write character, stream mode
4928
@cindex stream mode, write character
4929
@cindex file operation, write character
4930
 
4931
@table @asis
4932
@item @emph{Description}:
4933
Write a single character in stream mode by bypassing normal formatted
4934
output. Stream I/O should not be mixed with normal record-oriented
4935
(formatted or unformatted) I/O on the same unit; the results are unpredictable.
4936
 
4937
This intrinsic is provided in both subroutine and function forms; however,
4938
only one form can be used in any given program unit.
4939
 
4940
Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4941
@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4942
Programmers should consider the use of new stream IO feature in new code
4943
for future portability. See also @ref{Fortran 2003 status}.
4944
 
4945
@item @emph{Standard}:
4946
GNU extension
4947
 
4948
@item @emph{Class}:
4949
Subroutine, function
4950
 
4951
@item @emph{Syntax}:
4952
@multitable @columnfractions .80
4953
@item @code{CALL FPUTC(UNIT, C [, STATUS])}
4954
@item @code{STATUS = FPUTC(UNIT, C)}
4955
@end multitable
4956
 
4957
@item @emph{Arguments}:
4958
@multitable @columnfractions .15 .70
4959
@item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4960
@item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4961
kind.
4962
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4963
Returns 0 on success, -1 on end-of-file and a system specific positive
4964
error code otherwise.
4965
@end multitable
4966
 
4967
@item @emph{Example}:
4968
@smallexample
4969
PROGRAM test_fputc
4970
  CHARACTER(len=10) :: str = "gfortran"
4971
  INTEGER :: fd = 42, i
4972
 
4973
  OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4974
  DO i = 1, len_trim(str)
4975
    CALL fputc(fd, str(i:i))
4976
  END DO
4977
  CLOSE(fd)
4978
END PROGRAM
4979
@end smallexample
4980
 
4981
@item @emph{See also}:
4982
@ref{FPUT}, @ref{FGET}, @ref{FGETC}
4983
@end table
4984
 
4985
 
4986
 
4987
@node FRACTION
4988
@section @code{FRACTION} --- Fractional part of the model representation
4989
@fnindex FRACTION
4990
@cindex real number, fraction
4991
@cindex floating point, fraction
4992
 
4993
@table @asis
4994
@item @emph{Description}:
4995
@code{FRACTION(X)} returns the fractional part of the model
4996
representation of @code{X}.
4997
 
4998
@item @emph{Standard}:
4999
Fortran 95 and later
5000
 
5001
@item @emph{Class}:
5002
Elemental function
5003
 
5004
@item @emph{Syntax}:
5005
@code{Y = FRACTION(X)}
5006
 
5007
@item @emph{Arguments}:
5008
@multitable @columnfractions .15 .70
5009
@item @var{X} @tab The type of the argument shall be a @code{REAL}.
5010
@end multitable
5011
 
5012
@item @emph{Return value}:
5013
The return value is of the same type and kind as the argument.
5014
The fractional part of the model representation of @code{X} is returned;
5015
it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5016
 
5017
@item @emph{Example}:
5018
@smallexample
5019
program test_fraction
5020
  real :: x
5021
  x = 178.1387e-4
5022
  print *, fraction(x), x * radix(x)**(-exponent(x))
5023
end program test_fraction
5024
@end smallexample
5025
 
5026
@end table
5027
 
5028
 
5029
 
5030
@node FREE
5031
@section @code{FREE} --- Frees memory
5032
@fnindex FREE
5033
@cindex pointer, cray
5034
 
5035
@table @asis
5036
@item @emph{Description}:
5037
Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5038
intrinsic is an extension intended to be used with Cray pointers, and is
5039
provided in GNU Fortran to allow user to compile legacy code. For
5040
new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5041
@code{DEALLOCATE}.
5042
 
5043
@item @emph{Standard}:
5044
GNU extension
5045
 
5046
@item @emph{Class}:
5047
Subroutine
5048
 
5049
@item @emph{Syntax}:
5050
@code{CALL FREE(PTR)}
5051
 
5052
@item @emph{Arguments}:
5053
@multitable @columnfractions .15 .70
5054
@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5055
location of the memory that should be de-allocated.
5056
@end multitable
5057
 
5058
@item @emph{Return value}:
5059
None
5060
 
5061
@item @emph{Example}:
5062
See @code{MALLOC} for an example.
5063
 
5064
@item @emph{See also}:
5065
@ref{MALLOC}
5066
@end table
5067
 
5068
 
5069
 
5070
@node FSEEK
5071
@section @code{FSEEK} --- Low level file positioning subroutine
5072
@fnindex FSEEK
5073
@cindex file operation, seek
5074
@cindex file operation, position
5075
 
5076
@table @asis
5077
@item @emph{Description}:
5078
Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5079
is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5080
if set to 1, @var{OFFSET} is taken to be relative to the current position
5081
@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5082
On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5083
fails silently.
5084
 
5085
This intrinsic routine is not fully backwards compatible with @command{g77}.
5086
In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5087
@var{STATUS} variable. If FSEEK is used in old code, change
5088
@smallexample
5089
  CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5090
@end smallexample
5091
to
5092
@smallexample
5093
  INTEGER :: status
5094
  CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5095
  IF (status /= 0) GOTO label
5096
@end smallexample
5097
 
5098
Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5099
Programmers should consider the use of new stream IO feature in new code
5100
for future portability. See also @ref{Fortran 2003 status}.
5101
 
5102
@item @emph{Standard}:
5103
GNU extension
5104
 
5105
@item @emph{Class}:
5106
Subroutine
5107
 
5108
@item @emph{Syntax}:
5109
@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5110
 
5111
@item @emph{Arguments}:
5112
@multitable @columnfractions .15 .70
5113
@item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
5114
@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5115
@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5116
Its value shall be either 0, 1 or 2.
5117
@item @var{STATUS} @tab (Optional) shall be a scalar of type
5118
@code{INTEGER(4)}.
5119
@end multitable
5120
 
5121
@item @emph{Example}:
5122
@smallexample
5123
PROGRAM test_fseek
5124
  INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5125
  INTEGER :: fd, offset, ierr
5126
 
5127
  ierr   = 0
5128
  offset = 5
5129
  fd     = 10
5130
 
5131
  OPEN(UNIT=fd, FILE="fseek.test")
5132
  CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
5133
  print *, FTELL(fd), ierr
5134
 
5135
  CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
5136
  print *, FTELL(fd), ierr
5137
 
5138
  CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
5139
  print *, FTELL(fd), ierr
5140
 
5141
  CLOSE(UNIT=fd)
5142
END PROGRAM
5143
@end smallexample
5144
 
5145
@item @emph{See also}:
5146
@ref{FTELL}
5147
@end table
5148
 
5149
 
5150
 
5151
@node FSTAT
5152
@section @code{FSTAT} --- Get file status
5153
@fnindex FSTAT
5154
@cindex file system, file status
5155
 
5156
@table @asis
5157
@item @emph{Description}:
5158
@code{FSTAT} is identical to @ref{STAT}, except that information about an
5159
already opened file is obtained.
5160
 
5161
The elements in @code{VALUES} are the same as described by @ref{STAT}.
5162
 
5163
This intrinsic is provided in both subroutine and function forms; however,
5164
only one form can be used in any given program unit.
5165
 
5166
@item @emph{Standard}:
5167
GNU extension
5168
 
5169
@item @emph{Class}:
5170
Subroutine, function
5171
 
5172
@item @emph{Syntax}:
5173
@multitable @columnfractions .80
5174
@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5175
@item @code{STATUS = FSTAT(UNIT, VALUES)}
5176
@end multitable
5177
 
5178
@item @emph{Arguments}:
5179
@multitable @columnfractions .15 .70
5180
@item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
5181
@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5182
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5183
on success and a system specific error code otherwise.
5184
@end multitable
5185
 
5186
@item @emph{Example}:
5187
See @ref{STAT} for an example.
5188
 
5189
@item @emph{See also}:
5190
To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5191
@end table
5192
 
5193
 
5194
 
5195
@node FTELL
5196
@section @code{FTELL} --- Current stream position
5197
@fnindex FTELL
5198
@cindex file operation, position
5199
 
5200
@table @asis
5201
@item @emph{Description}:
5202
Retrieves the current position within an open file.
5203
 
5204
This intrinsic is provided in both subroutine and function forms; however,
5205
only one form can be used in any given program unit.
5206
 
5207
@item @emph{Standard}:
5208
GNU extension
5209
 
5210
@item @emph{Class}:
5211
Subroutine, function
5212
 
5213
@item @emph{Syntax}:
5214
@multitable @columnfractions .80
5215
@item @code{CALL FTELL(UNIT, OFFSET)}
5216
@item @code{OFFSET = FTELL(UNIT)}
5217
@end multitable
5218
 
5219
@item @emph{Arguments}:
5220
@multitable @columnfractions .15 .70
5221
@item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
5222
@item @var{UNIT}    @tab Shall of type @code{INTEGER}.
5223
@end multitable
5224
 
5225
@item @emph{Return value}:
5226
In either syntax, @var{OFFSET} is set to the current offset of unit
5227
number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5228
 
5229
@item @emph{Example}:
5230
@smallexample
5231
PROGRAM test_ftell
5232
  INTEGER :: i
5233
  OPEN(10, FILE="temp.dat")
5234
  CALL ftell(10,i)
5235
  WRITE(*,*) i
5236
END PROGRAM
5237
@end smallexample
5238
 
5239
@item @emph{See also}:
5240
@ref{FSEEK}
5241
@end table
5242
 
5243
 
5244
 
5245
@node GAMMA
5246
@section @code{GAMMA} --- Gamma function
5247
@fnindex GAMMA
5248
@fnindex DGAMMA
5249
@cindex Gamma function
5250
@cindex Factorial function
5251
 
5252
@table @asis
5253
@item @emph{Description}:
5254
@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5255
integer values of @var{X} the Gamma function simplifies to the factorial
5256
function @math{\Gamma(x)=(x-1)!}.
5257
 
5258
@tex
5259
$$
5260
\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5261
$$
5262
@end tex
5263
 
5264
@item @emph{Standard}:
5265
Fortran 2008 and later
5266
 
5267
@item @emph{Class}:
5268
Elemental function
5269
 
5270
@item @emph{Syntax}:
5271
@code{X = GAMMA(X)}
5272
 
5273
@item @emph{Arguments}:
5274
@multitable @columnfractions .15 .70
5275
@item @var{X} @tab Shall be of type @code{REAL} and neither zero
5276
nor a negative integer.
5277
@end multitable
5278
 
5279
@item @emph{Return value}:
5280
The return value is of type @code{REAL} of the same kind as @var{X}.
5281
 
5282
@item @emph{Example}:
5283
@smallexample
5284
program test_gamma
5285
  real :: x = 1.0
5286
  x = gamma(x) ! returns 1.0
5287
end program test_gamma
5288
@end smallexample
5289
 
5290
@item @emph{Specific names}:
5291
@multitable @columnfractions .20 .20 .20 .25
5292
@item Name             @tab Argument         @tab Return type       @tab Standard
5293
@item @code{GAMMA(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
5294
@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
5295
@end multitable
5296
 
5297
@item @emph{See also}:
5298
Logarithm of the Gamma function: @ref{LOG_GAMMA}
5299
 
5300
@end table
5301
 
5302
 
5303
 
5304
@node GERROR
5305
@section @code{GERROR} --- Get last system error message
5306
@fnindex GERROR
5307
@cindex system, error handling
5308
 
5309
@table @asis
5310
@item @emph{Description}:
5311
Returns the system error message corresponding to the last system error.
5312
This resembles the functionality of @code{strerror(3)} in C.
5313
 
5314
@item @emph{Standard}:
5315
GNU extension
5316
 
5317
@item @emph{Class}:
5318
Subroutine
5319
 
5320
@item @emph{Syntax}:
5321
@code{CALL GERROR(RESULT)}
5322
 
5323
@item @emph{Arguments}:
5324
@multitable @columnfractions .15 .70
5325
@item @var{RESULT}  @tab Shall of type @code{CHARACTER} and of default
5326
@end multitable
5327
 
5328
@item @emph{Example}:
5329
@smallexample
5330
PROGRAM test_gerror
5331
  CHARACTER(len=100) :: msg
5332
  CALL gerror(msg)
5333
  WRITE(*,*) msg
5334
END PROGRAM
5335
@end smallexample
5336
 
5337
@item @emph{See also}:
5338
@ref{IERRNO}, @ref{PERROR}
5339
@end table
5340
 
5341
 
5342
 
5343
@node GETARG
5344
@section @code{GETARG} --- Get command line arguments
5345
@fnindex GETARG
5346
@cindex command-line arguments
5347
@cindex arguments, to program
5348
 
5349
@table @asis
5350
@item @emph{Description}:
5351
Retrieve the @var{POS}-th argument that was passed on the
5352
command line when the containing program was invoked.
5353
 
5354
This intrinsic routine is provided for backwards compatibility with
5355
GNU Fortran 77.  In new code, programmers should consider the use of
5356
the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5357
standard.
5358
 
5359
@item @emph{Standard}:
5360
GNU extension
5361
 
5362
@item @emph{Class}:
5363
Subroutine
5364
 
5365
@item @emph{Syntax}:
5366
@code{CALL GETARG(POS, VALUE)}
5367
 
5368
@item @emph{Arguments}:
5369
@multitable @columnfractions .15 .70
5370
@item @var{POS}   @tab Shall be of type @code{INTEGER} and not wider than
5371
the default integer kind; @math{@var{POS} \geq 0}
5372
@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5373
kind.
5374
@item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5375
@end multitable
5376
 
5377
@item @emph{Return value}:
5378
After @code{GETARG} returns, the @var{VALUE} argument holds the
5379
@var{POS}th command line argument. If @var{VALUE} can not hold the
5380
argument, it is truncated to fit the length of @var{VALUE}. If there are
5381
less than @var{POS} arguments specified at the command line, @var{VALUE}
5382
will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5383
to the name of the program (on systems that support this feature).
5384
 
5385
@item @emph{Example}:
5386
@smallexample
5387
PROGRAM test_getarg
5388
  INTEGER :: i
5389
  CHARACTER(len=32) :: arg
5390
 
5391
  DO i = 1, iargc()
5392
    CALL getarg(i, arg)
5393
    WRITE (*,*) arg
5394
  END DO
5395
END PROGRAM
5396
@end smallexample
5397
 
5398
@item @emph{See also}:
5399
GNU Fortran 77 compatibility function: @ref{IARGC}
5400
 
5401
Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5402
@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5403
@end table
5404
 
5405
 
5406
 
5407
@node GET_COMMAND
5408
@section @code{GET_COMMAND} --- Get the entire command line
5409
@fnindex GET_COMMAND
5410
@cindex command-line arguments
5411
@cindex arguments, to program
5412
 
5413
@table @asis
5414
@item @emph{Description}:
5415
Retrieve the entire command line that was used to invoke the program.
5416
 
5417
@item @emph{Standard}:
5418
Fortran 2003 and later
5419
 
5420
@item @emph{Class}:
5421
Subroutine
5422
 
5423
@item @emph{Syntax}:
5424
@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5425
 
5426
@item @emph{Arguments}:
5427
@multitable @columnfractions .15 .70
5428
@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5429
of default kind.
5430
@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5431
default kind.
5432
@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5433
default kind.
5434
@end multitable
5435
 
5436
@item @emph{Return value}:
5437
If @var{COMMAND} is present, stores the entire command line that was used
5438
to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5439
assigned the length of the command line. If @var{STATUS} is present, it
5440
is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5441
short to store the command line, or a positive value in case of an error.
5442
 
5443
@item @emph{Example}:
5444
@smallexample
5445
PROGRAM test_get_command
5446
  CHARACTER(len=255) :: cmd
5447
  CALL get_command(cmd)
5448
  WRITE (*,*) TRIM(cmd)
5449
END PROGRAM
5450
@end smallexample
5451
 
5452
@item @emph{See also}:
5453
@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5454
@end table
5455
 
5456
 
5457
 
5458
@node GET_COMMAND_ARGUMENT
5459
@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5460
@fnindex GET_COMMAND_ARGUMENT
5461
@cindex command-line arguments
5462
@cindex arguments, to program
5463
 
5464
@table @asis
5465
@item @emph{Description}:
5466
Retrieve the @var{NUMBER}-th argument that was passed on the
5467
command line when the containing program was invoked.
5468
 
5469
@item @emph{Standard}:
5470
Fortran 2003 and later
5471
 
5472
@item @emph{Class}:
5473
Subroutine
5474
 
5475
@item @emph{Syntax}:
5476
@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5477
 
5478
@item @emph{Arguments}:
5479
@multitable @columnfractions .15 .70
5480
@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5481
default kind, @math{@var{NUMBER} \geq 0}
5482
@item @var{VALUE}  @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5483
and of default kind.
5484
@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5485
and of default kind.
5486
@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5487
and of default kind.
5488
@end multitable
5489
 
5490
@item @emph{Return value}:
5491
After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5492
@var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5493
truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5494
arguments specified at the command line, @var{VALUE} will be filled with blanks.
5495
If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5496
systems that support this feature). The @var{LENGTH} argument contains the
5497
length of the @var{NUMBER}-th command line argument. If the argument retrieval
5498
fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5499
command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5500
zero.
5501
 
5502
@item @emph{Example}:
5503
@smallexample
5504
PROGRAM test_get_command_argument
5505
  INTEGER :: i
5506
  CHARACTER(len=32) :: arg
5507
 
5508
  i = 0
5509
  DO
5510
    CALL get_command_argument(i, arg)
5511
    IF (LEN_TRIM(arg) == 0) EXIT
5512
 
5513
    WRITE (*,*) TRIM(arg)
5514
    i = i+1
5515
  END DO
5516
END PROGRAM
5517
@end smallexample
5518
 
5519
@item @emph{See also}:
5520
@ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5521
@end table
5522
 
5523
 
5524
 
5525
@node GETCWD
5526
@section @code{GETCWD} --- Get current working directory
5527
@fnindex GETCWD
5528
@cindex system, working directory
5529
 
5530
@table @asis
5531
@item @emph{Description}:
5532
Get current working directory.
5533
 
5534
This intrinsic is provided in both subroutine and function forms; however,
5535
only one form can be used in any given program unit.
5536
 
5537
@item @emph{Standard}:
5538
GNU extension
5539
 
5540
@item @emph{Class}:
5541
Subroutine, function
5542
 
5543
@item @emph{Syntax}:
5544
@multitable @columnfractions .80
5545
@item @code{CALL GETCWD(C [, STATUS])}
5546
@item @code{STATUS = GETCWD(C)}
5547
@end multitable
5548
 
5549
@item @emph{Arguments}:
5550
@multitable @columnfractions .15 .70
5551
@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5552
@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5553
a system specific and nonzero error code otherwise.
5554
@end multitable
5555
 
5556
@item @emph{Example}:
5557
@smallexample
5558
PROGRAM test_getcwd
5559
  CHARACTER(len=255) :: cwd
5560
  CALL getcwd(cwd)
5561
  WRITE(*,*) TRIM(cwd)
5562
END PROGRAM
5563
@end smallexample
5564
 
5565
@item @emph{See also}:
5566
@ref{CHDIR}
5567
@end table
5568
 
5569
 
5570
 
5571
@node GETENV
5572
@section @code{GETENV} --- Get an environmental variable
5573
@fnindex GETENV
5574
@cindex environment variable
5575
 
5576
@table @asis
5577
@item @emph{Description}:
5578
Get the @var{VALUE} of the environmental variable @var{NAME}.
5579
 
5580
This intrinsic routine is provided for backwards compatibility with
5581
GNU Fortran 77.  In new code, programmers should consider the use of
5582
the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5583
2003 standard.
5584
 
5585
Note that @code{GETENV} need not be thread-safe. It is the
5586
responsibility of the user to ensure that the environment is not being
5587
updated concurrently with a call to the @code{GETENV} intrinsic.
5588
 
5589
@item @emph{Standard}:
5590
GNU extension
5591
 
5592
@item @emph{Class}:
5593
Subroutine
5594
 
5595
@item @emph{Syntax}:
5596
@code{CALL GETENV(NAME, VALUE)}
5597
 
5598
@item @emph{Arguments}:
5599
@multitable @columnfractions .15 .70
5600
@item @var{NAME}  @tab Shall be of type @code{CHARACTER} and of default kind.
5601
@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5602
@end multitable
5603
 
5604
@item @emph{Return value}:
5605
Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5606
not large enough to hold the data, it is truncated. If @var{NAME}
5607
is not set, @var{VALUE} will be filled with blanks.
5608
 
5609
@item @emph{Example}:
5610
@smallexample
5611
PROGRAM test_getenv
5612
  CHARACTER(len=255) :: homedir
5613
  CALL getenv("HOME", homedir)
5614
  WRITE (*,*) TRIM(homedir)
5615
END PROGRAM
5616
@end smallexample
5617
 
5618
@item @emph{See also}:
5619
@ref{GET_ENVIRONMENT_VARIABLE}
5620
@end table
5621
 
5622
 
5623
 
5624
@node GET_ENVIRONMENT_VARIABLE
5625
@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5626
@fnindex GET_ENVIRONMENT_VARIABLE
5627
@cindex environment variable
5628
 
5629
@table @asis
5630
@item @emph{Description}:
5631
Get the @var{VALUE} of the environmental variable @var{NAME}.
5632
 
5633
Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5634
is the responsibility of the user to ensure that the environment is
5635
not being updated concurrently with a call to the
5636
@code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5637
 
5638
@item @emph{Standard}:
5639
Fortran 2003 and later
5640
 
5641
@item @emph{Class}:
5642
Subroutine
5643
 
5644
@item @emph{Syntax}:
5645
@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5646
 
5647
@item @emph{Arguments}:
5648
@multitable @columnfractions .15 .70
5649
@item @var{NAME}      @tab Shall be a scalar of type @code{CHARACTER}
5650
and of default kind.
5651
@item @var{VALUE}     @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5652
and of default kind.
5653
@item @var{LENGTH}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
5654
and of default kind.
5655
@item @var{STATUS}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
5656
and of default kind.
5657
@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5658
and of default kind.
5659
@end multitable
5660
 
5661
@item @emph{Return value}:
5662
Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5663
not large enough to hold the data, it is truncated. If @var{NAME}
5664
is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5665
contains the length needed for storing the environment variable @var{NAME}
5666
or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5667
but too short for the environment variable; it is 1 if the environment
5668
variable does not exist and 2 if the processor does not support environment
5669
variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5670
present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5671
are significant; otherwise they are not part of the environment variable
5672
name.
5673
 
5674
@item @emph{Example}:
5675
@smallexample
5676
PROGRAM test_getenv
5677
  CHARACTER(len=255) :: homedir
5678
  CALL get_environment_variable("HOME", homedir)
5679
  WRITE (*,*) TRIM(homedir)
5680
END PROGRAM
5681
@end smallexample
5682
@end table
5683
 
5684
 
5685
 
5686
@node GETGID
5687
@section @code{GETGID} --- Group ID function
5688
@fnindex GETGID
5689
@cindex system, group ID
5690
 
5691
@table @asis
5692
@item @emph{Description}:
5693
Returns the numerical group ID of the current process.
5694
 
5695
@item @emph{Standard}:
5696
GNU extension
5697
 
5698
@item @emph{Class}:
5699
Function
5700
 
5701
@item @emph{Syntax}:
5702
@code{RESULT = GETGID()}
5703
 
5704
@item @emph{Return value}:
5705
The return value of @code{GETGID} is an @code{INTEGER} of the default
5706
kind.
5707
 
5708
 
5709
@item @emph{Example}:
5710
See @code{GETPID} for an example.
5711
 
5712
@item @emph{See also}:
5713
@ref{GETPID}, @ref{GETUID}
5714
@end table
5715
 
5716
 
5717
 
5718
@node GETLOG
5719
@section @code{GETLOG} --- Get login name
5720
@fnindex GETLOG
5721
@cindex system, login name
5722
@cindex login name
5723
 
5724
@table @asis
5725
@item @emph{Description}:
5726
Gets the username under which the program is running.
5727
 
5728
@item @emph{Standard}:
5729
GNU extension
5730
 
5731
@item @emph{Class}:
5732
Subroutine
5733
 
5734
@item @emph{Syntax}:
5735
@code{CALL GETLOG(C)}
5736
 
5737
@item @emph{Arguments}:
5738
@multitable @columnfractions .15 .70
5739
@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5740
@end multitable
5741
 
5742
@item @emph{Return value}:
5743
Stores the current user name in @var{LOGIN}.  (On systems where POSIX
5744
functions @code{geteuid} and @code{getpwuid} are not available, and
5745
the @code{getlogin} function is not implemented either, this will
5746
return a blank string.)
5747
 
5748
@item @emph{Example}:
5749
@smallexample
5750
PROGRAM TEST_GETLOG
5751
  CHARACTER(32) :: login
5752
  CALL GETLOG(login)
5753
  WRITE(*,*) login
5754
END PROGRAM
5755
@end smallexample
5756
 
5757
@item @emph{See also}:
5758
@ref{GETUID}
5759
@end table
5760
 
5761
 
5762
 
5763
@node GETPID
5764
@section @code{GETPID} --- Process ID function
5765
@fnindex GETPID
5766
@cindex system, process ID
5767
@cindex process ID
5768
 
5769
@table @asis
5770
@item @emph{Description}:
5771
Returns the numerical process identifier of the current process.
5772
 
5773
@item @emph{Standard}:
5774
GNU extension
5775
 
5776
@item @emph{Class}:
5777
Function
5778
 
5779
@item @emph{Syntax}:
5780
@code{RESULT = GETPID()}
5781
 
5782
@item @emph{Return value}:
5783
The return value of @code{GETPID} is an @code{INTEGER} of the default
5784
kind.
5785
 
5786
 
5787
@item @emph{Example}:
5788
@smallexample
5789
program info
5790
  print *, "The current process ID is ", getpid()
5791
  print *, "Your numerical user ID is ", getuid()
5792
  print *, "Your numerical group ID is ", getgid()
5793
end program info
5794
@end smallexample
5795
 
5796
@item @emph{See also}:
5797
@ref{GETGID}, @ref{GETUID}
5798
@end table
5799
 
5800
 
5801
 
5802
@node GETUID
5803
@section @code{GETUID} --- User ID function
5804
@fnindex GETUID
5805
@cindex system, user ID
5806
@cindex user id
5807
 
5808
@table @asis
5809
@item @emph{Description}:
5810
Returns the numerical user ID of the current process.
5811
 
5812
@item @emph{Standard}:
5813
GNU extension
5814
 
5815
@item @emph{Class}:
5816
Function
5817
 
5818
@item @emph{Syntax}:
5819
@code{RESULT = GETUID()}
5820
 
5821
@item @emph{Return value}:
5822
The return value of @code{GETUID} is an @code{INTEGER} of the default
5823
kind.
5824
 
5825
 
5826
@item @emph{Example}:
5827
See @code{GETPID} for an example.
5828
 
5829
@item @emph{See also}:
5830
@ref{GETPID}, @ref{GETLOG}
5831
@end table
5832
 
5833
 
5834
 
5835
@node GMTIME
5836
@section @code{GMTIME} --- Convert time to GMT info
5837
@fnindex GMTIME
5838
@cindex time, conversion to GMT info
5839
 
5840
@table @asis
5841
@item @emph{Description}:
5842
Given a system time value @var{TIME} (as provided by the @code{TIME8}
5843
intrinsic), fills @var{VALUES} with values extracted from it appropriate
5844
to the UTC time zone (Universal Coordinated Time, also known in some
5845
countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5846
 
5847
@item @emph{Standard}:
5848
GNU extension
5849
 
5850
@item @emph{Class}:
5851
Subroutine
5852
 
5853
@item @emph{Syntax}:
5854
@code{CALL GMTIME(TIME, VALUES)}
5855
 
5856
@item @emph{Arguments}:
5857
@multitable @columnfractions .15 .70
5858
@item @var{TIME}   @tab An @code{INTEGER} scalar expression
5859
corresponding to a system time, with @code{INTENT(IN)}.
5860
@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5861
with @code{INTENT(OUT)}.
5862
@end multitable
5863
 
5864
@item @emph{Return value}:
5865
The elements of @var{VALUES} are assigned as follows:
5866
@enumerate
5867
@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5868
seconds
5869
@item Minutes after the hour, range 0--59
5870
@item Hours past midnight, range 0--23
5871
@item Day of month, range 0--31
5872
@item Number of months since January, range 0--12
5873
@item Years since 1900
5874
@item Number of days since Sunday, range 0--6
5875
@item Days since January 1
5876
@item Daylight savings indicator: positive if daylight savings is in
5877
effect, zero if not, and negative if the information is not available.
5878
@end enumerate
5879
 
5880
@item @emph{See also}:
5881
@ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5882
 
5883
@end table
5884
 
5885
 
5886
 
5887
@node HOSTNM
5888
@section @code{HOSTNM} --- Get system host name
5889
@fnindex HOSTNM
5890
@cindex system, host name
5891
 
5892
@table @asis
5893
@item @emph{Description}:
5894
Retrieves the host name of the system on which the program is running.
5895
 
5896
This intrinsic is provided in both subroutine and function forms; however,
5897
only one form can be used in any given program unit.
5898
 
5899
@item @emph{Standard}:
5900
GNU extension
5901
 
5902
@item @emph{Class}:
5903
Subroutine, function
5904
 
5905
@item @emph{Syntax}:
5906
@multitable @columnfractions .80
5907
@item @code{CALL HOSTNM(C [, STATUS])}
5908
@item @code{STATUS = HOSTNM(NAME)}
5909
@end multitable
5910
 
5911
@item @emph{Arguments}:
5912
@multitable @columnfractions .15 .70
5913
@item @var{C}    @tab Shall of type @code{CHARACTER} and of default kind.
5914
@item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
5915
Returns 0 on success, or a system specific error code otherwise.
5916
@end multitable
5917
 
5918
@item @emph{Return value}:
5919
In either syntax, @var{NAME} is set to the current hostname if it can
5920
be obtained, or to a blank string otherwise.
5921
 
5922
@end table
5923
 
5924
 
5925
 
5926
@node HUGE
5927
@section @code{HUGE} --- Largest number of a kind
5928
@fnindex HUGE
5929
@cindex limits, largest number
5930
@cindex model representation, largest number
5931
 
5932
@table @asis
5933
@item @emph{Description}:
5934
@code{HUGE(X)} returns the largest number that is not an infinity in
5935
the model of the type of @code{X}.
5936
 
5937
@item @emph{Standard}:
5938
Fortran 95 and later
5939
 
5940
@item @emph{Class}:
5941
Inquiry function
5942
 
5943
@item @emph{Syntax}:
5944
@code{RESULT = HUGE(X)}
5945
 
5946
@item @emph{Arguments}:
5947
@multitable @columnfractions .15 .70
5948
@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5949
@end multitable
5950
 
5951
@item @emph{Return value}:
5952
The return value is of the same type and kind as @var{X}
5953
 
5954
@item @emph{Example}:
5955
@smallexample
5956
program test_huge_tiny
5957
  print *, huge(0), huge(0.0), huge(0.0d0)
5958
  print *, tiny(0.0), tiny(0.0d0)
5959
end program test_huge_tiny
5960
@end smallexample
5961
@end table
5962
 
5963
 
5964
 
5965
@node HYPOT
5966
@section @code{HYPOT} --- Euclidean distance function
5967
@fnindex HYPOT
5968
@cindex Euclidean distance
5969
 
5970
@table @asis
5971
@item @emph{Description}:
5972
@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5973
@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5974
 
5975
@item @emph{Standard}:
5976
Fortran 2008 and later
5977
 
5978
@item @emph{Class}:
5979
Elemental function
5980
 
5981
@item @emph{Syntax}:
5982
@code{RESULT = HYPOT(X, Y)}
5983
 
5984
@item @emph{Arguments}:
5985
@multitable @columnfractions .15 .70
5986
@item @var{X} @tab The type shall be @code{REAL}.
5987
@item @var{Y} @tab The type and kind type parameter shall be the same as
5988
@var{X}.
5989
@end multitable
5990
 
5991
@item @emph{Return value}:
5992
The return value has the same type and kind type parameter as @var{X}.
5993
 
5994
@item @emph{Example}:
5995
@smallexample
5996
program test_hypot
5997
  real(4) :: x = 1.e0_4, y = 0.5e0_4
5998
  x = hypot(x,y)
5999
end program test_hypot
6000
@end smallexample
6001
@end table
6002
 
6003
 
6004
 
6005
@node IACHAR
6006
@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6007
@fnindex IACHAR
6008
@cindex @acronym{ASCII} collating sequence
6009
@cindex collating sequence, @acronym{ASCII}
6010
@cindex conversion, to integer
6011
 
6012
@table @asis
6013
@item @emph{Description}:
6014
@code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6015
in the first character position of @code{C}.
6016
 
6017
@item @emph{Standard}:
6018
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6019
 
6020
@item @emph{Class}:
6021
Elemental function
6022
 
6023
@item @emph{Syntax}:
6024
@code{RESULT = IACHAR(C [, KIND])}
6025
 
6026
@item @emph{Arguments}:
6027
@multitable @columnfractions .15 .70
6028
@item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6029
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6030
expression indicating the kind parameter of the result.
6031
@end multitable
6032
 
6033
@item @emph{Return value}:
6034
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6035
@var{KIND} is absent, the return value is of default integer kind.
6036
 
6037
@item @emph{Example}:
6038
@smallexample
6039
program test_iachar
6040
  integer i
6041
  i = iachar(' ')
6042
end program test_iachar
6043
@end smallexample
6044
 
6045
@item @emph{Note}:
6046
See @ref{ICHAR} for a discussion of converting between numerical values
6047
and formatted string representations.
6048
 
6049
@item @emph{See also}:
6050
@ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6051
 
6052
@end table
6053
 
6054
 
6055
 
6056
@node IALL
6057
@section @code{IALL} --- Bitwise AND of array elements
6058
@fnindex IALL
6059
@cindex array, AND
6060
@cindex bits, AND of array elements
6061
 
6062
@table @asis
6063
@item @emph{Description}:
6064
Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6065
if the corresponding element in @var{MASK} is @code{TRUE}.
6066
 
6067
@item @emph{Standard}:
6068
Fortran 2008 and later
6069
 
6070
@item @emph{Class}:
6071
Transformational function
6072
 
6073
@item @emph{Syntax}:
6074
@multitable @columnfractions .80
6075
@item @code{RESULT = IALL(ARRAY[, MASK])}
6076
@item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6077
@end multitable
6078
 
6079
@item @emph{Arguments}:
6080
@multitable @columnfractions .15 .70
6081
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6082
@item @var{DIM}   @tab (Optional) shall be a scalar of type
6083
@code{INTEGER} with a value in the range from 1 to n, where n
6084
equals the rank of @var{ARRAY}.
6085
@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6086
and either be a scalar or an array of the same shape as @var{ARRAY}.
6087
@end multitable
6088
 
6089
@item @emph{Return value}:
6090
The result is of the same type as @var{ARRAY}.
6091
 
6092
If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6093
@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6094
the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6095
dimension @var{DIM} dropped is returned.
6096
 
6097
@item @emph{Example}:
6098
@smallexample
6099
PROGRAM test_iall
6100
  INTEGER(1) :: a(2)
6101
 
6102
  a(1) = b'00100100'
6103
  a(2) = b'01101010'
6104
 
6105
  ! prints 00100000
6106
  PRINT '(b8.8)', IALL(a)
6107
END PROGRAM
6108
@end smallexample
6109
 
6110
@item @emph{See also}:
6111
@ref{IANY}, @ref{IPARITY}, @ref{IAND}
6112
@end table
6113
 
6114
 
6115
 
6116
@node IAND
6117
@section @code{IAND} --- Bitwise logical and
6118
@fnindex IAND
6119
@cindex bitwise logical and
6120
@cindex logical and, bitwise
6121
 
6122
@table @asis
6123
@item @emph{Description}:
6124
Bitwise logical @code{AND}.
6125
 
6126
@item @emph{Standard}:
6127
Fortran 95 and later
6128
 
6129
@item @emph{Class}:
6130
Elemental function
6131
 
6132
@item @emph{Syntax}:
6133
@code{RESULT = IAND(I, J)}
6134
 
6135
@item @emph{Arguments}:
6136
@multitable @columnfractions .15 .70
6137
@item @var{I} @tab The type shall be @code{INTEGER}.
6138
@item @var{J} @tab The type shall be @code{INTEGER}, of the same
6139
kind as @var{I}.  (As a GNU extension, different kinds are also
6140
permitted.)
6141
@end multitable
6142
 
6143
@item @emph{Return value}:
6144
The return type is @code{INTEGER}, of the same kind as the
6145
arguments.  (If the argument kinds differ, it is of the same kind as
6146
the larger argument.)
6147
 
6148
@item @emph{Example}:
6149
@smallexample
6150
PROGRAM test_iand
6151
  INTEGER :: a, b
6152
  DATA a / Z'F' /, b / Z'3' /
6153
  WRITE (*,*) IAND(a, b)
6154
END PROGRAM
6155
@end smallexample
6156
 
6157
@item @emph{See also}:
6158
@ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6159
 
6160
@end table
6161
 
6162
 
6163
 
6164
@node IANY
6165
@section @code{IANY} --- Bitwise OR of array elements
6166
@fnindex IANY
6167
@cindex array, OR
6168
@cindex bits, OR of array elements
6169
 
6170
@table @asis
6171
@item @emph{Description}:
6172
Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6173
dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6174
 
6175
@item @emph{Standard}:
6176
Fortran 2008 and later
6177
 
6178
@item @emph{Class}:
6179
Transformational function
6180
 
6181
@item @emph{Syntax}:
6182
@multitable @columnfractions .80
6183
@item @code{RESULT = IANY(ARRAY[, MASK])}
6184
@item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6185
@end multitable
6186
 
6187
@item @emph{Arguments}:
6188
@multitable @columnfractions .15 .70
6189
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6190
@item @var{DIM}   @tab (Optional) shall be a scalar of type
6191
@code{INTEGER} with a value in the range from 1 to n, where n
6192
equals the rank of @var{ARRAY}.
6193
@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6194
and either be a scalar or an array of the same shape as @var{ARRAY}.
6195
@end multitable
6196
 
6197
@item @emph{Return value}:
6198
The result is of the same type as @var{ARRAY}.
6199
 
6200
If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6201
@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6202
the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6203
dimension @var{DIM} dropped is returned.
6204
 
6205
@item @emph{Example}:
6206
@smallexample
6207
PROGRAM test_iany
6208
  INTEGER(1) :: a(2)
6209
 
6210
  a(1) = b'00100100'
6211
  a(2) = b'01101010'
6212
 
6213
  ! prints 01101110
6214
  PRINT '(b8.8)', IANY(a)
6215
END PROGRAM
6216
@end smallexample
6217
 
6218
@item @emph{See also}:
6219
@ref{IPARITY}, @ref{IALL}, @ref{IOR}
6220
@end table
6221
 
6222
 
6223
 
6224
@node IARGC
6225
@section @code{IARGC} --- Get the number of command line arguments
6226
@fnindex IARGC
6227
@cindex command-line arguments
6228
@cindex command-line arguments, number of
6229
@cindex arguments, to program
6230
 
6231
@table @asis
6232
@item @emph{Description}:
6233
@code{IARGC} returns the number of arguments passed on the
6234
command line when the containing program was invoked.
6235
 
6236
This intrinsic routine is provided for backwards compatibility with
6237
GNU Fortran 77.  In new code, programmers should consider the use of
6238
the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6239
standard.
6240
 
6241
@item @emph{Standard}:
6242
GNU extension
6243
 
6244
@item @emph{Class}:
6245
Function
6246
 
6247
@item @emph{Syntax}:
6248
@code{RESULT = IARGC()}
6249
 
6250
@item @emph{Arguments}:
6251
None.
6252
 
6253
@item @emph{Return value}:
6254
The number of command line arguments, type @code{INTEGER(4)}.
6255
 
6256
@item @emph{Example}:
6257
See @ref{GETARG}
6258
 
6259
@item @emph{See also}:
6260
GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6261
 
6262
Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6263
@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6264
@end table
6265
 
6266
 
6267
 
6268
@node IBCLR
6269
@section @code{IBCLR} --- Clear bit
6270
@fnindex IBCLR
6271
@cindex bits, unset
6272
@cindex bits, clear
6273
 
6274
@table @asis
6275
@item @emph{Description}:
6276
@code{IBCLR} returns the value of @var{I} with the bit at position
6277
@var{POS} set to zero.
6278
 
6279
@item @emph{Standard}:
6280
Fortran 95 and later
6281
 
6282
@item @emph{Class}:
6283
Elemental function
6284
 
6285
@item @emph{Syntax}:
6286
@code{RESULT = IBCLR(I, POS)}
6287
 
6288
@item @emph{Arguments}:
6289
@multitable @columnfractions .15 .70
6290
@item @var{I} @tab The type shall be @code{INTEGER}.
6291
@item @var{POS} @tab The type shall be @code{INTEGER}.
6292
@end multitable
6293
 
6294
@item @emph{Return value}:
6295
The return value is of type @code{INTEGER} and of the same kind as
6296
@var{I}.
6297
 
6298
@item @emph{See also}:
6299
@ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6300
 
6301
@end table
6302
 
6303
 
6304
 
6305
@node IBITS
6306
@section @code{IBITS} --- Bit extraction
6307
@fnindex IBITS
6308
@cindex bits, get
6309
@cindex bits, extract
6310
 
6311
@table @asis
6312
@item @emph{Description}:
6313
@code{IBITS} extracts a field of length @var{LEN} from @var{I},
6314
starting from bit position @var{POS} and extending left for @var{LEN}
6315
bits.  The result is right-justified and the remaining bits are
6316
zeroed.  The value of @code{POS+LEN} must be less than or equal to the
6317
value @code{BIT_SIZE(I)}.
6318
 
6319
@item @emph{Standard}:
6320
Fortran 95 and later
6321
 
6322
@item @emph{Class}:
6323
Elemental function
6324
 
6325
@item @emph{Syntax}:
6326
@code{RESULT = IBITS(I, POS, LEN)}
6327
 
6328
@item @emph{Arguments}:
6329
@multitable @columnfractions .15 .70
6330
@item @var{I}   @tab The type shall be @code{INTEGER}.
6331
@item @var{POS} @tab The type shall be @code{INTEGER}.
6332
@item @var{LEN} @tab The type shall be @code{INTEGER}.
6333
@end multitable
6334
 
6335
@item @emph{Return value}:
6336
The return value is of type @code{INTEGER} and of the same kind as
6337
@var{I}.
6338
 
6339
@item @emph{See also}:
6340
@ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6341
@end table
6342
 
6343
 
6344
 
6345
@node IBSET
6346
@section @code{IBSET} --- Set bit
6347
@fnindex IBSET
6348
@cindex bits, set
6349
 
6350
@table @asis
6351
@item @emph{Description}:
6352
@code{IBSET} returns the value of @var{I} with the bit at position
6353
@var{POS} set to one.
6354
 
6355
@item @emph{Standard}:
6356
Fortran 95 and later
6357
 
6358
@item @emph{Class}:
6359
Elemental function
6360
 
6361
@item @emph{Syntax}:
6362
@code{RESULT = IBSET(I, POS)}
6363
 
6364
@item @emph{Arguments}:
6365
@multitable @columnfractions .15 .70
6366
@item @var{I} @tab The type shall be @code{INTEGER}.
6367
@item @var{POS} @tab The type shall be @code{INTEGER}.
6368
@end multitable
6369
 
6370
@item @emph{Return value}:
6371
The return value is of type @code{INTEGER} and of the same kind as
6372
@var{I}.
6373
 
6374
@item @emph{See also}:
6375
@ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6376
 
6377
@end table
6378
 
6379
 
6380
 
6381
@node ICHAR
6382
@section @code{ICHAR} --- Character-to-integer conversion function
6383
@fnindex ICHAR
6384
@cindex conversion, to integer
6385
 
6386
@table @asis
6387
@item @emph{Description}:
6388
@code{ICHAR(C)} returns the code for the character in the first character
6389
position of @code{C} in the system's native character set.
6390
The correspondence between characters and their codes is not necessarily
6391
the same across different GNU Fortran implementations.
6392
 
6393
@item @emph{Standard}:
6394
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6395
 
6396
@item @emph{Class}:
6397
Elemental function
6398
 
6399
@item @emph{Syntax}:
6400
@code{RESULT = ICHAR(C [, KIND])}
6401
 
6402
@item @emph{Arguments}:
6403
@multitable @columnfractions .15 .70
6404
@item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6405
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6406
expression indicating the kind parameter of the result.
6407
@end multitable
6408
 
6409
@item @emph{Return value}:
6410
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6411
@var{KIND} is absent, the return value is of default integer kind.
6412
 
6413
@item @emph{Example}:
6414
@smallexample
6415
program test_ichar
6416
  integer i
6417
  i = ichar(' ')
6418
end program test_ichar
6419
@end smallexample
6420
 
6421
@item @emph{Specific names}:
6422
@multitable @columnfractions .20 .20 .20 .25
6423
@item Name             @tab Argument             @tab Return type       @tab Standard
6424
@item @code{ICHAR(C)}  @tab @code{CHARACTER C}   @tab @code{INTEGER(4)}    @tab Fortran 77 and later
6425
@end multitable
6426
 
6427
@item @emph{Note}:
6428
No intrinsic exists to convert between a numeric value and a formatted
6429
character string representation -- for instance, given the
6430
@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6431
@code{REAL} value with the value 154, or vice versa. Instead, this
6432
functionality is provided by internal-file I/O, as in the following
6433
example:
6434
@smallexample
6435
program read_val
6436
  integer value
6437
  character(len=10) string, string2
6438
  string = '154'
6439
 
6440
  ! Convert a string to a numeric value
6441
  read (string,'(I10)') value
6442
  print *, value
6443
 
6444
  ! Convert a value to a formatted string
6445
  write (string2,'(I10)') value
6446
  print *, string2
6447
end program read_val
6448
@end smallexample
6449
 
6450
@item @emph{See also}:
6451
@ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6452
 
6453
@end table
6454
 
6455
 
6456
 
6457
@node IDATE
6458
@section @code{IDATE} --- Get current local time subroutine (day/month/year)
6459
@fnindex IDATE
6460
@cindex date, current
6461
@cindex current date
6462
 
6463
@table @asis
6464
@item @emph{Description}:
6465
@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6466
current local time. The day (in the range 1-31), month (in the range 1-12),
6467
and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6468
The year has four significant digits.
6469
 
6470
@item @emph{Standard}:
6471
GNU extension
6472
 
6473
@item @emph{Class}:
6474
Subroutine
6475
 
6476
@item @emph{Syntax}:
6477
@code{CALL IDATE(VALUES)}
6478
 
6479
@item @emph{Arguments}:
6480
@multitable @columnfractions .15 .70
6481
@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6482
the kind shall be the default integer kind.
6483
@end multitable
6484
 
6485
@item @emph{Return value}:
6486
Does not return anything.
6487
 
6488
@item @emph{Example}:
6489
@smallexample
6490
program test_idate
6491
  integer, dimension(3) :: tarray
6492
  call idate(tarray)
6493
  print *, tarray(1)
6494
  print *, tarray(2)
6495
  print *, tarray(3)
6496
end program test_idate
6497
@end smallexample
6498
@end table
6499
 
6500
 
6501
 
6502
@node IEOR
6503
@section @code{IEOR} --- Bitwise logical exclusive or
6504
@fnindex IEOR
6505
@cindex bitwise logical exclusive or
6506
@cindex logical exclusive or, bitwise
6507
 
6508
@table @asis
6509
@item @emph{Description}:
6510
@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6511
@var{J}.
6512
 
6513
@item @emph{Standard}:
6514
Fortran 95 and later
6515
 
6516
@item @emph{Class}:
6517
Elemental function
6518
 
6519
@item @emph{Syntax}:
6520
@code{RESULT = IEOR(I, J)}
6521
 
6522
@item @emph{Arguments}:
6523
@multitable @columnfractions .15 .70
6524
@item @var{I} @tab The type shall be @code{INTEGER}.
6525
@item @var{J} @tab The type shall be @code{INTEGER}, of the same
6526
kind as @var{I}.  (As a GNU extension, different kinds are also
6527
permitted.)
6528
@end multitable
6529
 
6530
@item @emph{Return value}:
6531
The return type is @code{INTEGER}, of the same kind as the
6532
arguments.  (If the argument kinds differ, it is of the same kind as
6533
the larger argument.)
6534
 
6535
@item @emph{See also}:
6536
@ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6537
@end table
6538
 
6539
 
6540
 
6541
@node IERRNO
6542
@section @code{IERRNO} --- Get the last system error number
6543
@fnindex IERRNO
6544
@cindex system, error handling
6545
 
6546
@table @asis
6547
@item @emph{Description}:
6548
Returns the last system error number, as given by the C @code{errno}
6549
variable.
6550
 
6551
@item @emph{Standard}:
6552
GNU extension
6553
 
6554
@item @emph{Class}:
6555
Function
6556
 
6557
@item @emph{Syntax}:
6558
@code{RESULT = IERRNO()}
6559
 
6560
@item @emph{Arguments}:
6561
None.
6562
 
6563
@item @emph{Return value}:
6564
The return value is of type @code{INTEGER} and of the default integer
6565
kind.
6566
 
6567
@item @emph{See also}:
6568
@ref{PERROR}
6569
@end table
6570
 
6571
 
6572
 
6573
@node IMAGE_INDEX
6574
@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6575
@fnindex IMAGE_INDEX
6576
@cindex coarray, @code{IMAGE_INDEX}
6577
@cindex images, cosubscript to image index conversion
6578
 
6579
@table @asis
6580
@item @emph{Description}:
6581
Returns the image index belonging to a cosubscript.
6582
 
6583
@item @emph{Standard}:
6584
Fortran 2008 and later
6585
 
6586
@item @emph{Class}:
6587
Inquiry function.
6588
 
6589
@item @emph{Syntax}:
6590
@code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6591
 
6592
@item @emph{Arguments}: None.
6593
@multitable @columnfractions .15 .70
6594
@item @var{COARRAY} @tab Coarray of any type.
6595
@item @var{SUB}     @tab default integer rank-1 array of a size equal to
6596
the corank of @var{COARRAY}.
6597
@end multitable
6598
 
6599
 
6600
@item @emph{Return value}:
6601
Scalar default integer with the value of the image index which corresponds
6602
to the cosubscripts. For invalid cosubscripts the result is zero.
6603
 
6604
@item @emph{Example}:
6605
@smallexample
6606
INTEGER :: array[2,-1:4,8,*]
6607
! Writes  28 (or 0 if there are fewer than 28 images)
6608
WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6609
@end smallexample
6610
 
6611
@item @emph{See also}:
6612
@ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6613
@end table
6614
 
6615
 
6616
 
6617
@node INDEX intrinsic
6618
@section @code{INDEX} --- Position of a substring within a string
6619
@fnindex INDEX
6620
@cindex substring position
6621
@cindex string, find substring
6622
 
6623
@table @asis
6624
@item @emph{Description}:
6625
Returns the position of the start of the first occurrence of string
6626
@var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
6627
@var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If
6628
the @var{BACK} argument is present and true, the return value is the
6629
start of the last occurrence rather than the first.
6630
 
6631
@item @emph{Standard}:
6632
Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6633
 
6634
@item @emph{Class}:
6635
Elemental function
6636
 
6637
@item @emph{Syntax}:
6638
@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6639
 
6640
@item @emph{Arguments}:
6641
@multitable @columnfractions .15 .70
6642
@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6643
@code{INTENT(IN)}
6644
@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6645
@code{INTENT(IN)}
6646
@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6647
@code{INTENT(IN)}
6648
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6649
expression indicating the kind parameter of the result.
6650
@end multitable
6651
 
6652
@item @emph{Return value}:
6653
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6654
@var{KIND} is absent, the return value is of default integer kind.
6655
 
6656
@item @emph{Specific names}:
6657
@multitable @columnfractions .20 .20 .20 .25
6658
@item Name                            @tab Argument           @tab Return type       @tab Standard
6659
@item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER}   @tab @code{INTEGER(4)} @tab Fortran 77 and later
6660
@end multitable
6661
 
6662
@item @emph{See also}:
6663
@ref{SCAN}, @ref{VERIFY}
6664
@end table
6665
 
6666
 
6667
 
6668
@node INT
6669
@section @code{INT} --- Convert to integer type
6670
@fnindex INT
6671
@fnindex IFIX
6672
@fnindex IDINT
6673
@cindex conversion, to integer
6674
 
6675
@table @asis
6676
@item @emph{Description}:
6677
Convert to integer type
6678
 
6679
@item @emph{Standard}:
6680
Fortran 77 and later
6681
 
6682
@item @emph{Class}:
6683
Elemental function
6684
 
6685
@item @emph{Syntax}:
6686
@code{RESULT = INT(A [, KIND))}
6687
 
6688
@item @emph{Arguments}:
6689
@multitable @columnfractions .15 .70
6690
@item @var{A}    @tab Shall be of type @code{INTEGER},
6691
@code{REAL}, or @code{COMPLEX}.
6692
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6693
expression indicating the kind parameter of the result.
6694
@end multitable
6695
 
6696
@item @emph{Return value}:
6697
These functions return a @code{INTEGER} variable or array under
6698
the following rules:
6699
 
6700
@table @asis
6701
@item (A)
6702
If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6703
@item (B)
6704
If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6705
If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6706
the range of @var{A} and whose sign is the same as the sign of @var{A}.
6707
@item (C)
6708
If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6709
@end table
6710
 
6711
@item @emph{Example}:
6712
@smallexample
6713
program test_int
6714
  integer :: i = 42
6715
  complex :: z = (-3.7, 1.0)
6716
  print *, int(i)
6717
  print *, int(z), int(z,8)
6718
end program
6719
@end smallexample
6720
 
6721
@item @emph{Specific names}:
6722
@multitable @columnfractions .20 .20 .20 .25
6723
@item Name            @tab Argument          @tab Return type       @tab Standard
6724
@item @code{INT(A)}   @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6725
@item @code{IFIX(A)}  @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6726
@item @code{IDINT(A)} @tab @code{REAL(8) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6727
@end multitable
6728
 
6729
@end table
6730
 
6731
 
6732
@node INT2
6733
@section @code{INT2} --- Convert to 16-bit integer type
6734
@fnindex INT2
6735
@fnindex SHORT
6736
@cindex conversion, to integer
6737
 
6738
@table @asis
6739
@item @emph{Description}:
6740
Convert to a @code{KIND=2} integer type. This is equivalent to the
6741
standard @code{INT} intrinsic with an optional argument of
6742
@code{KIND=2}, and is only included for backwards compatibility.
6743
 
6744
The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6745
 
6746
@item @emph{Standard}:
6747
GNU extension
6748
 
6749
@item @emph{Class}:
6750
Elemental function
6751
 
6752
@item @emph{Syntax}:
6753
@code{RESULT = INT2(A)}
6754
 
6755
@item @emph{Arguments}:
6756
@multitable @columnfractions .15 .70
6757
@item @var{A}    @tab Shall be of type @code{INTEGER},
6758
@code{REAL}, or @code{COMPLEX}.
6759
@end multitable
6760
 
6761
@item @emph{Return value}:
6762
The return value is a @code{INTEGER(2)} variable.
6763
 
6764
@item @emph{See also}:
6765
@ref{INT}, @ref{INT8}, @ref{LONG}
6766
@end table
6767
 
6768
 
6769
 
6770
@node INT8
6771
@section @code{INT8} --- Convert to 64-bit integer type
6772
@fnindex INT8
6773
@cindex conversion, to integer
6774
 
6775
@table @asis
6776
@item @emph{Description}:
6777
Convert to a @code{KIND=8} integer type. This is equivalent to the
6778
standard @code{INT} intrinsic with an optional argument of
6779
@code{KIND=8}, and is only included for backwards compatibility.
6780
 
6781
@item @emph{Standard}:
6782
GNU extension
6783
 
6784
@item @emph{Class}:
6785
Elemental function
6786
 
6787
@item @emph{Syntax}:
6788
@code{RESULT = INT8(A)}
6789
 
6790
@item @emph{Arguments}:
6791
@multitable @columnfractions .15 .70
6792
@item @var{A}    @tab Shall be of type @code{INTEGER},
6793
@code{REAL}, or @code{COMPLEX}.
6794
@end multitable
6795
 
6796
@item @emph{Return value}:
6797
The return value is a @code{INTEGER(8)} variable.
6798
 
6799
@item @emph{See also}:
6800
@ref{INT}, @ref{INT2}, @ref{LONG}
6801
@end table
6802
 
6803
 
6804
 
6805
@node IOR
6806
@section @code{IOR} --- Bitwise logical or
6807
@fnindex IOR
6808
@cindex bitwise logical or
6809
@cindex logical or, bitwise
6810
 
6811
@table @asis
6812
@item @emph{Description}:
6813
@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6814
@var{J}.
6815
 
6816
@item @emph{Standard}:
6817
Fortran 95 and later
6818
 
6819
@item @emph{Class}:
6820
Elemental function
6821
 
6822
@item @emph{Syntax}:
6823
@code{RESULT = IOR(I, J)}
6824
 
6825
@item @emph{Arguments}:
6826
@multitable @columnfractions .15 .70
6827
@item @var{I} @tab The type shall be @code{INTEGER}.
6828
@item @var{J} @tab The type shall be @code{INTEGER}, of the same
6829
kind as @var{I}.  (As a GNU extension, different kinds are also
6830
permitted.)
6831
@end multitable
6832
 
6833
@item @emph{Return value}:
6834
The return type is @code{INTEGER}, of the same kind as the
6835
arguments.  (If the argument kinds differ, it is of the same kind as
6836
the larger argument.)
6837
 
6838
@item @emph{See also}:
6839
@ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6840
@end table
6841
 
6842
 
6843
 
6844
@node IPARITY
6845
@section @code{IPARITY} --- Bitwise XOR of array elements
6846
@fnindex IPARITY
6847
@cindex array, parity
6848
@cindex array, XOR
6849
@cindex bits, XOR of array elements
6850
 
6851
@table @asis
6852
@item @emph{Description}:
6853
Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6854
dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6855
 
6856
@item @emph{Standard}:
6857
Fortran 2008 and later
6858
 
6859
@item @emph{Class}:
6860
Transformational function
6861
 
6862
@item @emph{Syntax}:
6863
@multitable @columnfractions .80
6864
@item @code{RESULT = IPARITY(ARRAY[, MASK])}
6865
@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6866
@end multitable
6867
 
6868
@item @emph{Arguments}:
6869
@multitable @columnfractions .15 .70
6870
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6871
@item @var{DIM}   @tab (Optional) shall be a scalar of type
6872
@code{INTEGER} with a value in the range from 1 to n, where n
6873
equals the rank of @var{ARRAY}.
6874
@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6875
and either be a scalar or an array of the same shape as @var{ARRAY}.
6876
@end multitable
6877
 
6878
@item @emph{Return value}:
6879
The result is of the same type as @var{ARRAY}.
6880
 
6881
If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6882
@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6883
the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6884
dimension @var{DIM} dropped is returned.
6885
 
6886
@item @emph{Example}:
6887
@smallexample
6888
PROGRAM test_iparity
6889
  INTEGER(1) :: a(2)
6890
 
6891
  a(1) = b'00100100'
6892
  a(2) = b'01101010'
6893
 
6894
  ! prints 01001110
6895
  PRINT '(b8.8)', IPARITY(a)
6896
END PROGRAM
6897
@end smallexample
6898
 
6899
@item @emph{See also}:
6900
@ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6901
@end table
6902
 
6903
 
6904
 
6905
@node IRAND
6906
@section @code{IRAND} --- Integer pseudo-random number
6907
@fnindex IRAND
6908
@cindex random number generation
6909
 
6910
@table @asis
6911
@item @emph{Description}:
6912
@code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6913
distribution between 0 and a system-dependent limit (which is in most
6914
cases 2147483647). If @var{FLAG} is 0, the next number
6915
in the current sequence is returned; if @var{FLAG} is 1, the generator
6916
is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6917
it is used as a new seed with @code{SRAND}.
6918
 
6919
This intrinsic routine is provided for backwards compatibility with
6920
GNU Fortran 77. It implements a simple modulo generator as provided
6921
by @command{g77}. For new code, one should consider the use of
6922
@ref{RANDOM_NUMBER} as it implements a superior algorithm.
6923
 
6924
@item @emph{Standard}:
6925
GNU extension
6926
 
6927
@item @emph{Class}:
6928
Function
6929
 
6930
@item @emph{Syntax}:
6931
@code{RESULT = IRAND(I)}
6932
 
6933
@item @emph{Arguments}:
6934
@multitable @columnfractions .15 .70
6935
@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6936
@end multitable
6937
 
6938
@item @emph{Return value}:
6939
The return value is of @code{INTEGER(kind=4)} type.
6940
 
6941
@item @emph{Example}:
6942
@smallexample
6943
program test_irand
6944
  integer,parameter :: seed = 86456
6945
 
6946
  call srand(seed)
6947
  print *, irand(), irand(), irand(), irand()
6948
  print *, irand(seed), irand(), irand(), irand()
6949
end program test_irand
6950
@end smallexample
6951
 
6952
@end table
6953
 
6954
 
6955
 
6956
@node IS_IOSTAT_END
6957
@section @code{IS_IOSTAT_END} --- Test for end-of-file value
6958
@fnindex IS_IOSTAT_END
6959
@cindex @code{IOSTAT}, end of file
6960
 
6961
@table @asis
6962
@item @emph{Description}:
6963
@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6964
status ``end of file''. The function is equivalent to comparing the variable
6965
with the @code{IOSTAT_END} parameter of the intrinsic module
6966
@code{ISO_FORTRAN_ENV}.
6967
 
6968
@item @emph{Standard}:
6969
Fortran 2003 and later
6970
 
6971
@item @emph{Class}:
6972
Elemental function
6973
 
6974
@item @emph{Syntax}:
6975
@code{RESULT = IS_IOSTAT_END(I)}
6976
 
6977
@item @emph{Arguments}:
6978
@multitable @columnfractions .15 .70
6979
@item @var{I} @tab Shall be of the type @code{INTEGER}.
6980
@end multitable
6981
 
6982
@item @emph{Return value}:
6983
Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6984
@var{I} has the value which indicates an end of file condition for
6985
@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6986
 
6987
@item @emph{Example}:
6988
@smallexample
6989
PROGRAM iostat
6990
  IMPLICIT NONE
6991
  INTEGER :: stat, i
6992
  OPEN(88, FILE='test.dat')
6993
  READ(88, *, IOSTAT=stat) i
6994
  IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6995
END PROGRAM
6996
@end smallexample
6997
@end table
6998
 
6999
 
7000
 
7001
@node IS_IOSTAT_EOR
7002
@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7003
@fnindex IS_IOSTAT_EOR
7004
@cindex @code{IOSTAT}, end of record
7005
 
7006
@table @asis
7007
@item @emph{Description}:
7008
@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7009
status ``end of record''. The function is equivalent to comparing the
7010
variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7011
@code{ISO_FORTRAN_ENV}.
7012
 
7013
@item @emph{Standard}:
7014
Fortran 2003 and later
7015
 
7016
@item @emph{Class}:
7017
Elemental function
7018
 
7019
@item @emph{Syntax}:
7020
@code{RESULT = IS_IOSTAT_EOR(I)}
7021
 
7022
@item @emph{Arguments}:
7023
@multitable @columnfractions .15 .70
7024
@item @var{I} @tab Shall be of the type @code{INTEGER}.
7025
@end multitable
7026
 
7027
@item @emph{Return value}:
7028
Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7029
@var{I} has the value which indicates an end of file condition for
7030
@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7031
 
7032
@item @emph{Example}:
7033
@smallexample
7034
PROGRAM iostat
7035
  IMPLICIT NONE
7036
  INTEGER :: stat, i(50)
7037
  OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7038
  READ(88, IOSTAT=stat) i
7039
  IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7040
END PROGRAM
7041
@end smallexample
7042
@end table
7043
 
7044
 
7045
 
7046
@node ISATTY
7047
@section @code{ISATTY} --- Whether a unit is a terminal device.
7048
@fnindex ISATTY
7049
@cindex system, terminal
7050
 
7051
@table @asis
7052
@item @emph{Description}:
7053
Determine whether a unit is connected to a terminal device.
7054
 
7055
@item @emph{Standard}:
7056
GNU extension
7057
 
7058
@item @emph{Class}:
7059
Function
7060
 
7061
@item @emph{Syntax}:
7062
@code{RESULT = ISATTY(UNIT)}
7063
 
7064
@item @emph{Arguments}:
7065
@multitable @columnfractions .15 .70
7066
@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7067
@end multitable
7068
 
7069
@item @emph{Return value}:
7070
Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7071
device, @code{.FALSE.} otherwise.
7072
 
7073
@item @emph{Example}:
7074
@smallexample
7075
PROGRAM test_isatty
7076
  INTEGER(kind=1) :: unit
7077
  DO unit = 1, 10
7078
    write(*,*) isatty(unit=unit)
7079
  END DO
7080
END PROGRAM
7081
@end smallexample
7082
@item @emph{See also}:
7083
@ref{TTYNAM}
7084
@end table
7085
 
7086
 
7087
 
7088
@node ISHFT
7089
@section @code{ISHFT} --- Shift bits
7090
@fnindex ISHFT
7091
@cindex bits, shift
7092
 
7093
@table @asis
7094
@item @emph{Description}:
7095
@code{ISHFT} returns a value corresponding to @var{I} with all of the
7096
bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
7097
zero corresponds to a left shift, a value of zero corresponds to no
7098
shift, and a value less than zero corresponds to a right shift.  If the
7099
absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7100
value is undefined.  Bits shifted out from the left end or right end are
7101
lost; zeros are shifted in from the opposite end.
7102
 
7103
@item @emph{Standard}:
7104
Fortran 95 and later
7105
 
7106
@item @emph{Class}:
7107
Elemental function
7108
 
7109
@item @emph{Syntax}:
7110
@code{RESULT = ISHFT(I, SHIFT)}
7111
 
7112
@item @emph{Arguments}:
7113
@multitable @columnfractions .15 .70
7114
@item @var{I} @tab The type shall be @code{INTEGER}.
7115
@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7116
@end multitable
7117
 
7118
@item @emph{Return value}:
7119
The return value is of type @code{INTEGER} and of the same kind as
7120
@var{I}.
7121
 
7122
@item @emph{See also}:
7123
@ref{ISHFTC}
7124
@end table
7125
 
7126
 
7127
 
7128
@node ISHFTC
7129
@section @code{ISHFTC} --- Shift bits circularly
7130
@fnindex ISHFTC
7131
@cindex bits, shift circular
7132
 
7133
@table @asis
7134
@item @emph{Description}:
7135
@code{ISHFTC} returns a value corresponding to @var{I} with the
7136
rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7137
is, bits shifted out one end are shifted into the opposite end.  A value
7138
of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7139
zero corresponds to no shift, and a value less than zero corresponds to
7140
a right shift.  The absolute value of @var{SHIFT} must be less than
7141
@var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
7142
equivalent to @code{BIT_SIZE(I)}.
7143
 
7144
@item @emph{Standard}:
7145
Fortran 95 and later
7146
 
7147
@item @emph{Class}:
7148
Elemental function
7149
 
7150
@item @emph{Syntax}:
7151
@code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7152
 
7153
@item @emph{Arguments}:
7154
@multitable @columnfractions .15 .70
7155
@item @var{I} @tab The type shall be @code{INTEGER}.
7156
@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7157
@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7158
the value must be greater than zero and less than or equal to
7159
@code{BIT_SIZE(I)}.
7160
@end multitable
7161
 
7162
@item @emph{Return value}:
7163
The return value is of type @code{INTEGER} and of the same kind as
7164
@var{I}.
7165
 
7166
@item @emph{See also}:
7167
@ref{ISHFT}
7168
@end table
7169
 
7170
 
7171
 
7172
@node ISNAN
7173
@section @code{ISNAN} --- Test for a NaN
7174
@fnindex ISNAN
7175
@cindex IEEE, ISNAN
7176
 
7177
@table @asis
7178
@item @emph{Description}:
7179
@code{ISNAN} tests whether a floating-point value is an IEEE
7180
Not-a-Number (NaN).
7181
@item @emph{Standard}:
7182
GNU extension
7183
 
7184
@item @emph{Class}:
7185
Elemental function
7186
 
7187
@item @emph{Syntax}:
7188
@code{ISNAN(X)}
7189
 
7190
@item @emph{Arguments}:
7191
@multitable @columnfractions .15 .70
7192
@item @var{X} @tab Variable of the type @code{REAL}.
7193
 
7194
@end multitable
7195
 
7196
@item @emph{Return value}:
7197
Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7198
if @var{X} is a NaN and @code{FALSE} otherwise.
7199
 
7200
@item @emph{Example}:
7201
@smallexample
7202
program test_nan
7203
  implicit none
7204
  real :: x
7205
  x = -1.0
7206
  x = sqrt(x)
7207
  if (isnan(x)) stop '"x" is a NaN'
7208
end program test_nan
7209
@end smallexample
7210
@end table
7211
 
7212
 
7213
 
7214
@node ITIME
7215
@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7216
@fnindex ITIME
7217
@cindex time, current
7218
@cindex current time
7219
 
7220
@table @asis
7221
@item @emph{Description}:
7222
@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7223
current local time. The hour (in the range 1-24), minute (in the range 1-60),
7224
and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7225
respectively.
7226
 
7227
@item @emph{Standard}:
7228
GNU extension
7229
 
7230
@item @emph{Class}:
7231
Subroutine
7232
 
7233
@item @emph{Syntax}:
7234
@code{CALL ITIME(VALUES)}
7235
 
7236
@item @emph{Arguments}:
7237
@multitable @columnfractions .15 .70
7238
@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7239
and the kind shall be the default integer kind.
7240
@end multitable
7241
 
7242
@item @emph{Return value}:
7243
Does not return anything.
7244
 
7245
 
7246
@item @emph{Example}:
7247
@smallexample
7248
program test_itime
7249
  integer, dimension(3) :: tarray
7250
  call itime(tarray)
7251
  print *, tarray(1)
7252
  print *, tarray(2)
7253
  print *, tarray(3)
7254
end program test_itime
7255
@end smallexample
7256
@end table
7257
 
7258
 
7259
 
7260
@node KILL
7261
@section @code{KILL} --- Send a signal to a process
7262
@fnindex KILL
7263
 
7264
@table @asis
7265
@item @emph{Description}:
7266
@item @emph{Standard}:
7267
Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7268
See @code{kill(2)}.
7269
 
7270
This intrinsic is provided in both subroutine and function forms; however,
7271
only one form can be used in any given program unit.
7272
 
7273
@item @emph{Class}:
7274
Subroutine, function
7275
 
7276
@item @emph{Syntax}:
7277
@multitable @columnfractions .80
7278
@item @code{CALL KILL(C, VALUE [, STATUS])}
7279
@item @code{STATUS = KILL(C, VALUE)}
7280
@end multitable
7281
 
7282
@item @emph{Arguments}:
7283
@multitable @columnfractions .15 .70
7284
@item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7285
@code{INTENT(IN)}
7286
@item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7287
@code{INTENT(IN)}
7288
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7289
@code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7290
otherwise.
7291
@end multitable
7292
 
7293
@item @emph{See also}:
7294
@ref{ABORT}, @ref{EXIT}
7295
@end table
7296
 
7297
 
7298
 
7299
@node KIND
7300
@section @code{KIND} --- Kind of an entity
7301
@fnindex KIND
7302
@cindex kind
7303
 
7304
@table @asis
7305
@item @emph{Description}:
7306
@code{KIND(X)} returns the kind value of the entity @var{X}.
7307
 
7308
@item @emph{Standard}:
7309
Fortran 95 and later
7310
 
7311
@item @emph{Class}:
7312
Inquiry function
7313
 
7314
@item @emph{Syntax}:
7315
@code{K = KIND(X)}
7316
 
7317
@item @emph{Arguments}:
7318
@multitable @columnfractions .15 .70
7319
@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7320
@code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7321
@end multitable
7322
 
7323
@item @emph{Return value}:
7324
The return value is a scalar of type @code{INTEGER} and of the default
7325
integer kind.
7326
 
7327
@item @emph{Example}:
7328
@smallexample
7329
program test_kind
7330
  integer,parameter :: kc = kind(' ')
7331
  integer,parameter :: kl = kind(.true.)
7332
 
7333
  print *, "The default character kind is ", kc
7334
  print *, "The default logical kind is ", kl
7335
end program test_kind
7336
@end smallexample
7337
 
7338
@end table
7339
 
7340
 
7341
 
7342
@node LBOUND
7343
@section @code{LBOUND} --- Lower dimension bounds of an array
7344
@fnindex LBOUND
7345
@cindex array, lower bound
7346
 
7347
@table @asis
7348
@item @emph{Description}:
7349
Returns the lower bounds of an array, or a single lower bound
7350
along the @var{DIM} dimension.
7351
@item @emph{Standard}:
7352
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7353
 
7354
@item @emph{Class}:
7355
Inquiry function
7356
 
7357
@item @emph{Syntax}:
7358
@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7359
 
7360
@item @emph{Arguments}:
7361
@multitable @columnfractions .15 .70
7362
@item @var{ARRAY} @tab Shall be an array, of any type.
7363
@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7364
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7365
expression indicating the kind parameter of the result.
7366
@end multitable
7367
 
7368
@item @emph{Return value}:
7369
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7370
@var{KIND} is absent, the return value is of default integer kind.
7371
If @var{DIM} is absent, the result is an array of the lower bounds of
7372
@var{ARRAY}.  If @var{DIM} is present, the result is a scalar
7373
corresponding to the lower bound of the array along that dimension.  If
7374
@var{ARRAY} is an expression rather than a whole array or array
7375
structure component, or if it has a zero extent along the relevant
7376
dimension, the lower bound is taken to be 1.
7377
 
7378
@item @emph{See also}:
7379
@ref{UBOUND}, @ref{LCOBOUND}
7380
@end table
7381
 
7382
 
7383
 
7384
@node LCOBOUND
7385
@section @code{LCOBOUND} --- Lower codimension bounds of an array
7386
@fnindex LCOBOUND
7387
@cindex coarray, lower bound
7388
 
7389
@table @asis
7390
@item @emph{Description}:
7391
Returns the lower bounds of a coarray, or a single lower cobound
7392
along the @var{DIM} codimension.
7393
@item @emph{Standard}:
7394
Fortran 2008 and later
7395
 
7396
@item @emph{Class}:
7397
Inquiry function
7398
 
7399
@item @emph{Syntax}:
7400
@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7401
 
7402
@item @emph{Arguments}:
7403
@multitable @columnfractions .15 .70
7404
@item @var{ARRAY} @tab Shall be an coarray, of any type.
7405
@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7406
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7407
expression indicating the kind parameter of the result.
7408
@end multitable
7409
 
7410
@item @emph{Return value}:
7411
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7412
@var{KIND} is absent, the return value is of default integer kind.
7413
If @var{DIM} is absent, the result is an array of the lower cobounds of
7414
@var{COARRAY}.  If @var{DIM} is present, the result is a scalar
7415
corresponding to the lower cobound of the array along that codimension.
7416
 
7417
@item @emph{See also}:
7418
@ref{UCOBOUND}, @ref{LBOUND}
7419
@end table
7420
 
7421
 
7422
 
7423
@node LEADZ
7424
@section @code{LEADZ} --- Number of leading zero bits of an integer
7425
@fnindex LEADZ
7426
@cindex zero bits
7427
 
7428
@table @asis
7429
@item @emph{Description}:
7430
@code{LEADZ} returns the number of leading zero bits of an integer.
7431
 
7432
@item @emph{Standard}:
7433
Fortran 2008 and later
7434
 
7435
@item @emph{Class}:
7436
Elemental function
7437
 
7438
@item @emph{Syntax}:
7439
@code{RESULT = LEADZ(I)}
7440
 
7441
@item @emph{Arguments}:
7442
@multitable @columnfractions .15 .70
7443
@item @var{I} @tab Shall be of type @code{INTEGER}.
7444
@end multitable
7445
 
7446
@item @emph{Return value}:
7447
The type of the return value is the default @code{INTEGER}.
7448
If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7449
 
7450
@item @emph{Example}:
7451
@smallexample
7452
PROGRAM test_leadz
7453
  WRITE (*,*) BIT_SIZE(1)  ! prints 32
7454
  WRITE (*,*) LEADZ(1)     ! prints 31
7455
END PROGRAM
7456
@end smallexample
7457
 
7458
@item @emph{See also}:
7459
@ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7460
@end table
7461
 
7462
 
7463
 
7464
@node LEN
7465
@section @code{LEN} --- Length of a character entity
7466
@fnindex LEN
7467
@cindex string, length
7468
 
7469
@table @asis
7470
@item @emph{Description}:
7471
Returns the length of a character string.  If @var{STRING} is an array,
7472
the length of an element of @var{STRING} is returned.  Note that
7473
@var{STRING} need not be defined when this intrinsic is invoked, since
7474
only the length, not the content, of @var{STRING} is needed.
7475
 
7476
@item @emph{Standard}:
7477
Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7478
 
7479
@item @emph{Class}:
7480
Inquiry function
7481
 
7482
@item @emph{Syntax}:
7483
@code{L = LEN(STRING [, KIND])}
7484
 
7485
@item @emph{Arguments}:
7486
@multitable @columnfractions .15 .70
7487
@item @var{STRING} @tab Shall be a scalar or array of type
7488
@code{CHARACTER}, with @code{INTENT(IN)}
7489
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7490
expression indicating the kind parameter of the result.
7491
@end multitable
7492
 
7493
@item @emph{Return value}:
7494
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7495
@var{KIND} is absent, the return value is of default integer kind.
7496
 
7497
 
7498
@item @emph{Specific names}:
7499
@multitable @columnfractions .20 .20 .20 .25
7500
@item Name               @tab Argument          @tab Return type       @tab Standard
7501
@item @code{LEN(STRING)} @tab @code{CHARACTER}  @tab @code{INTEGER}    @tab Fortran 77 and later
7502
@end multitable
7503
 
7504
 
7505
@item @emph{See also}:
7506
@ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7507
@end table
7508
 
7509
 
7510
 
7511
@node LEN_TRIM
7512
@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7513
@fnindex LEN_TRIM
7514
@cindex string, length, without trailing whitespace
7515
 
7516
@table @asis
7517
@item @emph{Description}:
7518
Returns the length of a character string, ignoring any trailing blanks.
7519
 
7520
@item @emph{Standard}:
7521
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7522
 
7523
@item @emph{Class}:
7524
Elemental function
7525
 
7526
@item @emph{Syntax}:
7527
@code{RESULT = LEN_TRIM(STRING [, KIND])}
7528
 
7529
@item @emph{Arguments}:
7530
@multitable @columnfractions .15 .70
7531
@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7532
with @code{INTENT(IN)}
7533
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7534
expression indicating the kind parameter of the result.
7535
@end multitable
7536
 
7537
@item @emph{Return value}:
7538
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7539
@var{KIND} is absent, the return value is of default integer kind.
7540
 
7541
@item @emph{See also}:
7542
@ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7543
@end table
7544
 
7545
 
7546
 
7547
@node LGE
7548
@section @code{LGE} --- Lexical greater than or equal
7549
@fnindex LGE
7550
@cindex lexical comparison of strings
7551
@cindex string, comparison
7552
 
7553
@table @asis
7554
@item @emph{Description}:
7555
Determines whether one string is lexically greater than or equal to
7556
another string, where the two strings are interpreted as containing
7557
ASCII character codes.  If the String A and String B are not the same
7558
length, the shorter is compared as if spaces were appended to it to form
7559
a value that has the same length as the longer.
7560
 
7561
In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7562
@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7563
operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7564
that the latter use the processor's character ordering (which is not
7565
ASCII on some targets), whereas the former always use the ASCII
7566
ordering.
7567
 
7568
@item @emph{Standard}:
7569
Fortran 77 and later
7570
 
7571
@item @emph{Class}:
7572
Elemental function
7573
 
7574
@item @emph{Syntax}:
7575
@code{RESULT = LGE(STRING_A, STRING_B)}
7576
 
7577
@item @emph{Arguments}:
7578
@multitable @columnfractions .15 .70
7579
@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7580
@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7581
@end multitable
7582
 
7583
@item @emph{Return value}:
7584
Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7585
otherwise, based on the ASCII ordering.
7586
 
7587
@item @emph{Specific names}:
7588
@multitable @columnfractions .20 .20 .20 .25
7589
@item Name                           @tab Argument          @tab Return type       @tab Standard
7590
@item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7591
@end multitable
7592
 
7593
@item @emph{See also}:
7594
@ref{LGT}, @ref{LLE}, @ref{LLT}
7595
@end table
7596
 
7597
 
7598
 
7599
@node LGT
7600
@section @code{LGT} --- Lexical greater than
7601
@fnindex LGT
7602
@cindex lexical comparison of strings
7603
@cindex string, comparison
7604
 
7605
@table @asis
7606
@item @emph{Description}:
7607
Determines whether one string is lexically greater than another string,
7608
where the two strings are interpreted as containing ASCII character
7609
codes.  If the String A and String B are not the same length, the
7610
shorter is compared as if spaces were appended to it to form a value
7611
that has the same length as the longer.
7612
 
7613
In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7614
@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7615
operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7616
that the latter use the processor's character ordering (which is not
7617
ASCII on some targets), whereas the former always use the ASCII
7618
ordering.
7619
 
7620
@item @emph{Standard}:
7621
Fortran 77 and later
7622
 
7623
@item @emph{Class}:
7624
Elemental function
7625
 
7626
@item @emph{Syntax}:
7627
@code{RESULT = LGT(STRING_A, STRING_B)}
7628
 
7629
@item @emph{Arguments}:
7630
@multitable @columnfractions .15 .70
7631
@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7632
@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7633
@end multitable
7634
 
7635
@item @emph{Return value}:
7636
Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7637
otherwise, based on the ASCII ordering.
7638
 
7639
@item @emph{Specific names}:
7640
@multitable @columnfractions .20 .20 .20 .25
7641
@item Name                           @tab Argument          @tab Return type       @tab Standard
7642
@item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7643
@end multitable
7644
 
7645
@item @emph{See also}:
7646
@ref{LGE}, @ref{LLE}, @ref{LLT}
7647
@end table
7648
 
7649
 
7650
 
7651
@node LINK
7652
@section @code{LINK} --- Create a hard link
7653
@fnindex LINK
7654
@cindex file system, create link
7655
@cindex file system, hard link
7656
 
7657
@table @asis
7658
@item @emph{Description}:
7659
Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7660
character (@code{CHAR(0)}) can be used to mark the end of the names in
7661
@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7662
names are ignored.  If the @var{STATUS} argument is supplied, it
7663
contains 0 on success or a nonzero error code upon return; see
7664
@code{link(2)}.
7665
 
7666
This intrinsic is provided in both subroutine and function forms;
7667
however, only one form can be used in any given program unit.
7668
 
7669
@item @emph{Standard}:
7670
GNU extension
7671
 
7672
@item @emph{Class}:
7673
Subroutine, function
7674
 
7675
@item @emph{Syntax}:
7676
@multitable @columnfractions .80
7677
@item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7678
@item @code{STATUS = LINK(PATH1, PATH2)}
7679
@end multitable
7680
 
7681
@item @emph{Arguments}:
7682
@multitable @columnfractions .15 .70
7683
@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7684
@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7685
@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7686
@end multitable
7687
 
7688
@item @emph{See also}:
7689
@ref{SYMLNK}, @ref{UNLINK}
7690
@end table
7691
 
7692
 
7693
 
7694
@node LLE
7695
@section @code{LLE} --- Lexical less than or equal
7696
@fnindex LLE
7697
@cindex lexical comparison of strings
7698
@cindex string, comparison
7699
 
7700
@table @asis
7701
@item @emph{Description}:
7702
Determines whether one string is lexically less than or equal to another
7703
string, where the two strings are interpreted as containing ASCII
7704
character codes.  If the String A and String B are not the same length,
7705
the shorter is compared as if spaces were appended to it to form a value
7706
that has the same length as the longer.
7707
 
7708
In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7709
@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7710
operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7711
that the latter use the processor's character ordering (which is not
7712
ASCII on some targets), whereas the former always use the ASCII
7713
ordering.
7714
 
7715
@item @emph{Standard}:
7716
Fortran 77 and later
7717
 
7718
@item @emph{Class}:
7719
Elemental function
7720
 
7721
@item @emph{Syntax}:
7722
@code{RESULT = LLE(STRING_A, STRING_B)}
7723
 
7724
@item @emph{Arguments}:
7725
@multitable @columnfractions .15 .70
7726
@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7727
@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7728
@end multitable
7729
 
7730
@item @emph{Return value}:
7731
Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7732
otherwise, based on the ASCII ordering.
7733
 
7734
@item @emph{Specific names}:
7735
@multitable @columnfractions .20 .20 .20 .25
7736
@item Name                           @tab Argument          @tab Return type       @tab Standard
7737
@item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7738
@end multitable
7739
 
7740
@item @emph{See also}:
7741
@ref{LGE}, @ref{LGT}, @ref{LLT}
7742
@end table
7743
 
7744
 
7745
 
7746
@node LLT
7747
@section @code{LLT} --- Lexical less than
7748
@fnindex LLT
7749
@cindex lexical comparison of strings
7750
@cindex string, comparison
7751
 
7752
@table @asis
7753
@item @emph{Description}:
7754
Determines whether one string is lexically less than another string,
7755
where the two strings are interpreted as containing ASCII character
7756
codes.  If the String A and String B are not the same length, the
7757
shorter is compared as if spaces were appended to it to form a value
7758
that has the same length as the longer.
7759
 
7760
In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7761
@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7762
operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7763
that the latter use the processor's character ordering (which is not
7764
ASCII on some targets), whereas the former always use the ASCII
7765
ordering.
7766
 
7767
@item @emph{Standard}:
7768
Fortran 77 and later
7769
 
7770
@item @emph{Class}:
7771
Elemental function
7772
 
7773
@item @emph{Syntax}:
7774
@code{RESULT = LLT(STRING_A, STRING_B)}
7775
 
7776
@item @emph{Arguments}:
7777
@multitable @columnfractions .15 .70
7778
@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7779
@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7780
@end multitable
7781
 
7782
@item @emph{Return value}:
7783
Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7784
otherwise, based on the ASCII ordering.
7785
 
7786
@item @emph{Specific names}:
7787
@multitable @columnfractions .20 .20 .20 .25
7788
@item Name                           @tab Argument          @tab Return type       @tab Standard
7789
@item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7790
@end multitable
7791
 
7792
@item @emph{See also}:
7793
@ref{LGE}, @ref{LGT}, @ref{LLE}
7794
@end table
7795
 
7796
 
7797
 
7798
@node LNBLNK
7799
@section @code{LNBLNK} --- Index of the last non-blank character in a string
7800
@fnindex LNBLNK
7801
@cindex string, find non-blank character
7802
 
7803
@table @asis
7804
@item @emph{Description}:
7805
Returns the length of a character string, ignoring any trailing blanks.
7806
This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7807
included for backwards compatibility.
7808
 
7809
@item @emph{Standard}:
7810
GNU extension
7811
 
7812
@item @emph{Class}:
7813
Elemental function
7814
 
7815
@item @emph{Syntax}:
7816
@code{RESULT = LNBLNK(STRING)}
7817
 
7818
@item @emph{Arguments}:
7819
@multitable @columnfractions .15 .70
7820
@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7821
with @code{INTENT(IN)}
7822
@end multitable
7823
 
7824
@item @emph{Return value}:
7825
The return value is of @code{INTEGER(kind=4)} type.
7826
 
7827
@item @emph{See also}:
7828
@ref{INDEX intrinsic}, @ref{LEN_TRIM}
7829
@end table
7830
 
7831
 
7832
 
7833
@node LOC
7834
@section @code{LOC} --- Returns the address of a variable
7835
@fnindex LOC
7836
@cindex location of a variable in memory
7837
 
7838
@table @asis
7839
@item @emph{Description}:
7840
@code{LOC(X)} returns the address of @var{X} as an integer.
7841
 
7842
@item @emph{Standard}:
7843
GNU extension
7844
 
7845
@item @emph{Class}:
7846
Inquiry function
7847
 
7848
@item @emph{Syntax}:
7849
@code{RESULT = LOC(X)}
7850
 
7851
@item @emph{Arguments}:
7852
@multitable @columnfractions .15 .70
7853
@item @var{X} @tab Variable of any type.
7854
@end multitable
7855
 
7856
@item @emph{Return value}:
7857
The return value is of type @code{INTEGER}, with a @code{KIND}
7858
corresponding to the size (in bytes) of a memory address on the target
7859
machine.
7860
 
7861
@item @emph{Example}:
7862
@smallexample
7863
program test_loc
7864
  integer :: i
7865
  real :: r
7866
  i = loc(r)
7867
  print *, i
7868
end program test_loc
7869
@end smallexample
7870
@end table
7871
 
7872
 
7873
 
7874
@node LOG
7875
@section @code{LOG} --- Natural logarithm function
7876
@fnindex LOG
7877
@fnindex ALOG
7878
@fnindex DLOG
7879
@fnindex CLOG
7880
@fnindex ZLOG
7881
@fnindex CDLOG
7882
@cindex exponential function, inverse
7883
@cindex logarithm function
7884
@cindex natural logarithm function
7885
 
7886
@table @asis
7887
@item @emph{Description}:
7888
@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
7889
logarithm to the base @math{e}.
7890
 
7891
@item @emph{Standard}:
7892
Fortran 77 and later
7893
 
7894
@item @emph{Class}:
7895
Elemental function
7896
 
7897
@item @emph{Syntax}:
7898
@code{RESULT = LOG(X)}
7899
 
7900
@item @emph{Arguments}:
7901
@multitable @columnfractions .15 .70
7902
@item @var{X} @tab The type shall be @code{REAL} or
7903
@code{COMPLEX}.
7904
@end multitable
7905
 
7906
@item @emph{Return value}:
7907
The return value is of type @code{REAL} or @code{COMPLEX}.
7908
The kind type parameter is the same as @var{X}.
7909
If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7910
@math{-\pi \leq \omega \leq \pi}.
7911
 
7912
@item @emph{Example}:
7913
@smallexample
7914
program test_log
7915
  real(8) :: x = 2.7182818284590451_8
7916
  complex :: z = (1.0, 2.0)
7917
  x = log(x)    ! will yield (approximately) 1
7918
  z = log(z)
7919
end program test_log
7920
@end smallexample
7921
 
7922
@item @emph{Specific names}:
7923
@multitable @columnfractions .20 .20 .20 .25
7924
@item Name            @tab Argument          @tab Return type       @tab Standard
7925
@item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
7926
@item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
7927
@item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
7928
@item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7929
@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7930
@end multitable
7931
@end table
7932
 
7933
 
7934
 
7935
@node LOG10
7936
@section @code{LOG10} --- Base 10 logarithm function
7937
@fnindex LOG10
7938
@fnindex ALOG10
7939
@fnindex DLOG10
7940
@cindex exponential function, inverse
7941
@cindex logarithm function with base 10
7942
@cindex base 10 logarithm function
7943
 
7944
@table @asis
7945
@item @emph{Description}:
7946
@code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7947
 
7948
@item @emph{Standard}:
7949
Fortran 77 and later
7950
 
7951
@item @emph{Class}:
7952
Elemental function
7953
 
7954
@item @emph{Syntax}:
7955
@code{RESULT = LOG10(X)}
7956
 
7957
@item @emph{Arguments}:
7958
@multitable @columnfractions .15 .70
7959
@item @var{X} @tab The type shall be @code{REAL}.
7960
@end multitable
7961
 
7962
@item @emph{Return value}:
7963
The return value is of type @code{REAL} or @code{COMPLEX}.
7964
The kind type parameter is the same as @var{X}.
7965
 
7966
@item @emph{Example}:
7967
@smallexample
7968
program test_log10
7969
  real(8) :: x = 10.0_8
7970
  x = log10(x)
7971
end program test_log10
7972
@end smallexample
7973
 
7974
@item @emph{Specific names}:
7975
@multitable @columnfractions .20 .20 .20 .25
7976
@item Name            @tab Argument          @tab Return type       @tab Standard
7977
@item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
7978
@item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
7979
@end multitable
7980
@end table
7981
 
7982
 
7983
 
7984
@node LOG_GAMMA
7985
@section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7986
@fnindex LOG_GAMMA
7987
@fnindex LGAMMA
7988
@fnindex ALGAMA
7989
@fnindex DLGAMA
7990
@cindex Gamma function, logarithm of
7991
 
7992
@table @asis
7993
@item @emph{Description}:
7994
@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7995
of the Gamma (@math{\Gamma}) function.
7996
 
7997
@item @emph{Standard}:
7998
Fortran 2008 and later
7999
 
8000
@item @emph{Class}:
8001
Elemental function
8002
 
8003
@item @emph{Syntax}:
8004
@code{X = LOG_GAMMA(X)}
8005
 
8006
@item @emph{Arguments}:
8007
@multitable @columnfractions .15 .70
8008
@item @var{X} @tab Shall be of type @code{REAL} and neither zero
8009
nor a negative integer.
8010
@end multitable
8011
 
8012
@item @emph{Return value}:
8013
The return value is of type @code{REAL} of the same kind as @var{X}.
8014
 
8015
@item @emph{Example}:
8016
@smallexample
8017
program test_log_gamma
8018
  real :: x = 1.0
8019
  x = lgamma(x) ! returns 0.0
8020
end program test_log_gamma
8021
@end smallexample
8022
 
8023
@item @emph{Specific names}:
8024
@multitable @columnfractions .20 .20 .20 .25
8025
@item Name             @tab Argument         @tab Return type       @tab Standard
8026
@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
8027
@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
8028
@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
8029
@end multitable
8030
 
8031
@item @emph{See also}:
8032
Gamma function: @ref{GAMMA}
8033
 
8034
@end table
8035
 
8036
 
8037
 
8038
@node LOGICAL
8039
@section @code{LOGICAL} --- Convert to logical type
8040
@fnindex LOGICAL
8041
@cindex conversion, to logical
8042
 
8043
@table @asis
8044
@item @emph{Description}:
8045
Converts one kind of @code{LOGICAL} variable to another.
8046
 
8047
@item @emph{Standard}:
8048
Fortran 95 and later
8049
 
8050
@item @emph{Class}:
8051
Elemental function
8052
 
8053
@item @emph{Syntax}:
8054
@code{RESULT = LOGICAL(L [, KIND])}
8055
 
8056
@item @emph{Arguments}:
8057
@multitable @columnfractions .15 .70
8058
@item @var{L}    @tab The type shall be @code{LOGICAL}.
8059
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8060
expression indicating the kind parameter of the result.
8061
@end multitable
8062
 
8063
@item @emph{Return value}:
8064
The return value is a @code{LOGICAL} value equal to @var{L}, with a
8065
kind corresponding to @var{KIND}, or of the default logical kind if
8066
@var{KIND} is not given.
8067
 
8068
@item @emph{See also}:
8069
@ref{INT}, @ref{REAL}, @ref{CMPLX}
8070
@end table
8071
 
8072
 
8073
 
8074
@node LONG
8075
@section @code{LONG} --- Convert to integer type
8076
@fnindex LONG
8077
@cindex conversion, to integer
8078
 
8079
@table @asis
8080
@item @emph{Description}:
8081
Convert to a @code{KIND=4} integer type, which is the same size as a C
8082
@code{long} integer.  This is equivalent to the standard @code{INT}
8083
intrinsic with an optional argument of @code{KIND=4}, and is only
8084
included for backwards compatibility.
8085
 
8086
@item @emph{Standard}:
8087
GNU extension
8088
 
8089
@item @emph{Class}:
8090
Elemental function
8091
 
8092
@item @emph{Syntax}:
8093
@code{RESULT = LONG(A)}
8094
 
8095
@item @emph{Arguments}:
8096
@multitable @columnfractions .15 .70
8097
@item @var{A}    @tab Shall be of type @code{INTEGER},
8098
@code{REAL}, or @code{COMPLEX}.
8099
@end multitable
8100
 
8101
@item @emph{Return value}:
8102
The return value is a @code{INTEGER(4)} variable.
8103
 
8104
@item @emph{See also}:
8105
@ref{INT}, @ref{INT2}, @ref{INT8}
8106
@end table
8107
 
8108
 
8109
 
8110
@node LSHIFT
8111
@section @code{LSHIFT} --- Left shift bits
8112
@fnindex LSHIFT
8113
@cindex bits, shift left
8114
 
8115
@table @asis
8116
@item @emph{Description}:
8117
@code{LSHIFT} returns a value corresponding to @var{I} with all of the
8118
bits shifted left by @var{SHIFT} places.  If the absolute value of
8119
@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8120
Bits shifted out from the left end are lost; zeros are shifted in from
8121
the opposite end.
8122
 
8123
This function has been superseded by the @code{ISHFT} intrinsic, which
8124
is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8125
which is standard in Fortran 2008 and later.
8126
 
8127
@item @emph{Standard}:
8128
GNU extension
8129
 
8130
@item @emph{Class}:
8131
Elemental function
8132
 
8133
@item @emph{Syntax}:
8134
@code{RESULT = LSHIFT(I, SHIFT)}
8135
 
8136
@item @emph{Arguments}:
8137
@multitable @columnfractions .15 .70
8138
@item @var{I} @tab The type shall be @code{INTEGER}.
8139
@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8140
@end multitable
8141
 
8142
@item @emph{Return value}:
8143
The return value is of type @code{INTEGER} and of the same kind as
8144
@var{I}.
8145
 
8146
@item @emph{See also}:
8147
@ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8148
@ref{SHIFTR}
8149
 
8150
@end table
8151
 
8152
 
8153
 
8154
@node LSTAT
8155
@section @code{LSTAT} --- Get file status
8156
@fnindex LSTAT
8157
@cindex file system, file status
8158
 
8159
@table @asis
8160
@item @emph{Description}:
8161
@code{LSTAT} is identical to @ref{STAT}, except that if path is a
8162
symbolic link, then the link itself is statted, not the file that it
8163
refers to.
8164
 
8165
The elements in @code{VALUES} are the same as described by @ref{STAT}.
8166
 
8167
This intrinsic is provided in both subroutine and function forms;
8168
however, only one form can be used in any given program unit.
8169
 
8170
@item @emph{Standard}:
8171
GNU extension
8172
 
8173
@item @emph{Class}:
8174
Subroutine, function
8175
 
8176
@item @emph{Syntax}:
8177
@multitable @columnfractions .80
8178
@item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8179
@item @code{STATUS = LSTAT(NAME, VALUES)}
8180
@end multitable
8181
 
8182
@item @emph{Arguments}:
8183
@multitable @columnfractions .15 .70
8184
@item @var{NAME}   @tab The type shall be @code{CHARACTER} of the default
8185
kind, a valid path within the file system.
8186
@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8187
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8188
Returns 0 on success and a system specific error code otherwise.
8189
@end multitable
8190
 
8191
@item @emph{Example}:
8192
See @ref{STAT} for an example.
8193
 
8194
@item @emph{See also}:
8195
To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8196
@end table
8197
 
8198
 
8199
 
8200
@node LTIME
8201
@section @code{LTIME} --- Convert time to local time info
8202
@fnindex LTIME
8203
@cindex time, conversion to local time info
8204
 
8205
@table @asis
8206
@item @emph{Description}:
8207
Given a system time value @var{TIME} (as provided by the @code{TIME8}
8208
intrinsic), fills @var{VALUES} with values extracted from it appropriate
8209
to the local time zone using @code{localtime(3)}.
8210
 
8211
@item @emph{Standard}:
8212
GNU extension
8213
 
8214
@item @emph{Class}:
8215
Subroutine
8216
 
8217
@item @emph{Syntax}:
8218
@code{CALL LTIME(TIME, VALUES)}
8219
 
8220
@item @emph{Arguments}:
8221
@multitable @columnfractions .15 .70
8222
@item @var{TIME}  @tab An @code{INTEGER} scalar expression
8223
corresponding to a system time, with @code{INTENT(IN)}.
8224
@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8225
with @code{INTENT(OUT)}.
8226
@end multitable
8227
 
8228
@item @emph{Return value}:
8229
The elements of @var{VALUES} are assigned as follows:
8230
@enumerate
8231
@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8232
seconds
8233
@item Minutes after the hour, range 0--59
8234
@item Hours past midnight, range 0--23
8235
@item Day of month, range 0--31
8236
@item Number of months since January, range 0--12
8237
@item Years since 1900
8238
@item Number of days since Sunday, range 0--6
8239
@item Days since January 1
8240
@item Daylight savings indicator: positive if daylight savings is in
8241
effect, zero if not, and negative if the information is not available.
8242
@end enumerate
8243
 
8244
@item @emph{See also}:
8245
@ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8246
 
8247
@end table
8248
 
8249
 
8250
 
8251
@node MALLOC
8252
@section @code{MALLOC} --- Allocate dynamic memory
8253
@fnindex MALLOC
8254
@cindex pointer, cray
8255
 
8256
@table @asis
8257
@item @emph{Description}:
8258
@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8259
returns the address of the allocated memory. The @code{MALLOC} intrinsic
8260
is an extension intended to be used with Cray pointers, and is provided
8261
in GNU Fortran to allow the user to compile legacy code. For new code
8262
using Fortran 95 pointers, the memory allocation intrinsic is
8263
@code{ALLOCATE}.
8264
 
8265
@item @emph{Standard}:
8266
GNU extension
8267
 
8268
@item @emph{Class}:
8269
Function
8270
 
8271
@item @emph{Syntax}:
8272
@code{PTR = MALLOC(SIZE)}
8273
 
8274
@item @emph{Arguments}:
8275
@multitable @columnfractions .15 .70
8276
@item @var{SIZE} @tab The type shall be @code{INTEGER}.
8277
@end multitable
8278
 
8279
@item @emph{Return value}:
8280
The return value is of type @code{INTEGER(K)}, with @var{K} such that
8281
variables of type @code{INTEGER(K)} have the same size as
8282
C pointers (@code{sizeof(void *)}).
8283
 
8284
@item @emph{Example}:
8285
The following example demonstrates the use of @code{MALLOC} and
8286
@code{FREE} with Cray pointers.
8287
 
8288
@smallexample
8289
program test_malloc
8290
  implicit none
8291
  integer i
8292
  real*8 x(*), z
8293
  pointer(ptr_x,x)
8294
 
8295
  ptr_x = malloc(20*8)
8296
  do i = 1, 20
8297
    x(i) = sqrt(1.0d0 / i)
8298
  end do
8299
  z = 0
8300
  do i = 1, 20
8301
    z = z + x(i)
8302
    print *, z
8303
  end do
8304
  call free(ptr_x)
8305
end program test_malloc
8306
@end smallexample
8307
 
8308
@item @emph{See also}:
8309
@ref{FREE}
8310
@end table
8311
 
8312
 
8313
 
8314
@node MASKL
8315
@section @code{MASKL} --- Left justified mask
8316
@fnindex MASKL
8317
@cindex mask, left justified
8318
 
8319
@table @asis
8320
@item @emph{Description}:
8321
@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8322
remaining bits set to 0.
8323
 
8324
@item @emph{Standard}:
8325
Fortran 2008 and later
8326
 
8327
@item @emph{Class}:
8328
Elemental function
8329
 
8330
@item @emph{Syntax}:
8331
@code{RESULT = MASKL(I[, KIND])}
8332
 
8333
@item @emph{Arguments}:
8334
@multitable @columnfractions .15 .70
8335
@item @var{I} @tab Shall be of type @code{INTEGER}.
8336
@item @var{KIND} @tab Shall be a scalar constant expression of type
8337
@code{INTEGER}.
8338
@end multitable
8339
 
8340
@item @emph{Return value}:
8341
The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8342
specifies the kind value of the return type; otherwise, it is of the
8343
default integer kind.
8344
 
8345
@item @emph{See also}:
8346
@ref{MASKR}
8347
@end table
8348
 
8349
 
8350
 
8351
@node MASKR
8352
@section @code{MASKR} --- Right justified mask
8353
@fnindex MASKR
8354
@cindex mask, right justified
8355
 
8356
@table @asis
8357
@item @emph{Description}:
8358
@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8359
remaining bits set to 0.
8360
 
8361
@item @emph{Standard}:
8362
Fortran 2008 and later
8363
 
8364
@item @emph{Class}:
8365
Elemental function
8366
 
8367
@item @emph{Syntax}:
8368
@code{RESULT = MASKR(I[, KIND])}
8369
 
8370
@item @emph{Arguments}:
8371
@multitable @columnfractions .15 .70
8372
@item @var{I} @tab Shall be of type @code{INTEGER}.
8373
@item @var{KIND} @tab Shall be a scalar constant expression of type
8374
@code{INTEGER}.
8375
@end multitable
8376
 
8377
@item @emph{Return value}:
8378
The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8379
specifies the kind value of the return type; otherwise, it is of the
8380
default integer kind.
8381
 
8382
@item @emph{See also}:
8383
@ref{MASKL}
8384
@end table
8385
 
8386
 
8387
 
8388
@node MATMUL
8389
@section @code{MATMUL} --- matrix multiplication
8390
@fnindex MATMUL
8391
@cindex matrix multiplication
8392
@cindex product, matrix
8393
 
8394
@table @asis
8395
@item @emph{Description}:
8396
Performs a matrix multiplication on numeric or logical arguments.
8397
 
8398
@item @emph{Standard}:
8399
Fortran 95 and later
8400
 
8401
@item @emph{Class}:
8402
Transformational function
8403
 
8404
@item @emph{Syntax}:
8405
@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8406
 
8407
@item @emph{Arguments}:
8408
@multitable @columnfractions .15 .70
8409
@item @var{MATRIX_A} @tab An array of @code{INTEGER},
8410
@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8411
one or two.
8412
@item @var{MATRIX_B} @tab An array of @code{INTEGER},
8413
@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8414
type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8415
or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8416
equal to the last (or only) dimension of @var{MATRIX_A}.
8417
@end multitable
8418
 
8419
@item @emph{Return value}:
8420
The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
8421
kind of the result follow the usual type and kind promotion rules, as
8422
for the @code{*} or @code{.AND.} operators.
8423
 
8424
@item @emph{See also}:
8425
@end table
8426
 
8427
 
8428
 
8429
@node MAX
8430
@section @code{MAX} --- Maximum value of an argument list
8431
@fnindex MAX
8432
@fnindex MAX0
8433
@fnindex AMAX0
8434
@fnindex MAX1
8435
@fnindex AMAX1
8436
@fnindex DMAX1
8437
@cindex maximum value
8438
 
8439
@table @asis
8440
@item @emph{Description}:
8441
Returns the argument with the largest (most positive) value.
8442
 
8443
@item @emph{Standard}:
8444
Fortran 77 and later
8445
 
8446
@item @emph{Class}:
8447
Elemental function
8448
 
8449
@item @emph{Syntax}:
8450
@code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8451
 
8452
@item @emph{Arguments}:
8453
@multitable @columnfractions .15 .70
8454
@item @var{A1}          @tab The type shall be @code{INTEGER} or
8455
@code{REAL}.
8456
@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8457
as @var{A1}.  (As a GNU extension, arguments of different kinds are
8458
permitted.)
8459
@end multitable
8460
 
8461
@item @emph{Return value}:
8462
The return value corresponds to the maximum value among the arguments,
8463
and has the same type and kind as the first argument.
8464
 
8465
@item @emph{Specific names}:
8466
@multitable @columnfractions .20 .20 .20 .25
8467
@item Name             @tab Argument             @tab Return type         @tab Standard
8468
@item @code{MAX0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
8469
@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8470
@item @code{MAX1(A1)}  @tab @code{REAL A1}       @tab @code{INT(MAX(X))}  @tab Fortran 77 and later
8471
@item @code{AMAX1(A1)} @tab @code{REAL(4) A1}    @tab @code{REAL(4)}      @tab Fortran 77 and later
8472
@item @code{DMAX1(A1)} @tab @code{REAL(8) A1}    @tab @code{REAL(8)}      @tab Fortran 77 and later
8473
@end multitable
8474
 
8475
@item @emph{See also}:
8476
@ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8477
 
8478
@end table
8479
 
8480
 
8481
 
8482
@node MAXEXPONENT
8483
@section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8484
@fnindex MAXEXPONENT
8485
@cindex model representation, maximum exponent
8486
 
8487
@table @asis
8488
@item @emph{Description}:
8489
@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8490
type of @code{X}.
8491
 
8492
@item @emph{Standard}:
8493
Fortran 95 and later
8494
 
8495
@item @emph{Class}:
8496
Inquiry function
8497
 
8498
@item @emph{Syntax}:
8499
@code{RESULT = MAXEXPONENT(X)}
8500
 
8501
@item @emph{Arguments}:
8502
@multitable @columnfractions .15 .70
8503
@item @var{X} @tab Shall be of type @code{REAL}.
8504
@end multitable
8505
 
8506
@item @emph{Return value}:
8507
The return value is of type @code{INTEGER} and of the default integer
8508
kind.
8509
 
8510
@item @emph{Example}:
8511
@smallexample
8512
program exponents
8513
  real(kind=4) :: x
8514
  real(kind=8) :: y
8515
 
8516
  print *, minexponent(x), maxexponent(x)
8517
  print *, minexponent(y), maxexponent(y)
8518
end program exponents
8519
@end smallexample
8520
@end table
8521
 
8522
 
8523
 
8524
@node MAXLOC
8525
@section @code{MAXLOC} --- Location of the maximum value within an array
8526
@fnindex MAXLOC
8527
@cindex array, location of maximum element
8528
 
8529
@table @asis
8530
@item @emph{Description}:
8531
Determines the location of the element in the array with the maximum
8532
value, or, if the @var{DIM} argument is supplied, determines the
8533
locations of the maximum element along each row of the array in the
8534
@var{DIM} direction.  If @var{MASK} is present, only the elements for
8535
which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8536
element in the array has the maximum value, the location returned is
8537
that of the first such element in array element order.  If the array has
8538
zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8539
the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8540
and all of the elements of @var{MASK} along a given row are zero, the
8541
result value for that row is zero.
8542
 
8543
@item @emph{Standard}:
8544
Fortran 95 and later
8545
 
8546
@item @emph{Class}:
8547
Transformational function
8548
 
8549
@item @emph{Syntax}:
8550
@multitable @columnfractions .80
8551
@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8552
@item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8553
@end multitable
8554
 
8555
@item @emph{Arguments}:
8556
@multitable @columnfractions .15 .70
8557
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8558
@code{REAL}.
8559
@item @var{DIM}   @tab (Optional) Shall be a scalar of type
8560
@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8561
inclusive.  It may not be an optional dummy argument.
8562
@item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8563
and conformable with @var{ARRAY}.
8564
@end multitable
8565
 
8566
@item @emph{Return value}:
8567
If @var{DIM} is absent, the result is a rank-one array with a length
8568
equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8569
is an array with a rank one less than the rank of @var{ARRAY}, and a
8570
size corresponding to the size of @var{ARRAY} with the @var{DIM}
8571
dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8572
of one, the result is a scalar.  In all cases, the result is of default
8573
@code{INTEGER} type.
8574
 
8575
@item @emph{See also}:
8576
@ref{MAX}, @ref{MAXVAL}
8577
 
8578
@end table
8579
 
8580
 
8581
 
8582
@node MAXVAL
8583
@section @code{MAXVAL} --- Maximum value of an array
8584
@fnindex MAXVAL
8585
@cindex array, maximum value
8586
@cindex maximum value
8587
 
8588
@table @asis
8589
@item @emph{Description}:
8590
Determines the maximum value of the elements in an array value, or, if
8591
the @var{DIM} argument is supplied, determines the maximum value along
8592
each row of the array in the @var{DIM} direction.  If @var{MASK} is
8593
present, only the elements for which @var{MASK} is @code{.TRUE.} are
8594
considered.  If the array has zero size, or all of the elements of
8595
@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8596
if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8597
type.
8598
 
8599
@item @emph{Standard}:
8600
Fortran 95 and later
8601
 
8602
@item @emph{Class}:
8603
Transformational function
8604
 
8605
@item @emph{Syntax}:
8606
@multitable @columnfractions .80
8607
@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8608
@item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8609
@end multitable
8610
 
8611
@item @emph{Arguments}:
8612
@multitable @columnfractions .15 .70
8613
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8614
@code{REAL}.
8615
@item @var{DIM}   @tab (Optional) Shall be a scalar of type
8616
@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8617
inclusive.  It may not be an optional dummy argument.
8618
@item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8619
and conformable with @var{ARRAY}.
8620
@end multitable
8621
 
8622
@item @emph{Return value}:
8623
If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8624
is a scalar.  If @var{DIM} is present, the result is an array with a
8625
rank one less than the rank of @var{ARRAY}, and a size corresponding to
8626
the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8627
cases, the result is of the same type and kind as @var{ARRAY}.
8628
 
8629
@item @emph{See also}:
8630
@ref{MAX}, @ref{MAXLOC}
8631
@end table
8632
 
8633
 
8634
 
8635
@node MCLOCK
8636
@section @code{MCLOCK} --- Time function
8637
@fnindex MCLOCK
8638
@cindex time, clock ticks
8639
@cindex clock ticks
8640
 
8641
@table @asis
8642
@item @emph{Description}:
8643
Returns the number of clock ticks since the start of the process, based
8644
on the function @code{clock(3)} in the C standard library.
8645
 
8646
This intrinsic is not fully portable, such as to systems with 32-bit
8647
@code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8648
the values returned by this intrinsic might be, or become, negative, or
8649
numerically less than previous values, during a single run of the
8650
compiled program.
8651
 
8652
@item @emph{Standard}:
8653
GNU extension
8654
 
8655
@item @emph{Class}:
8656
Function
8657
 
8658
@item @emph{Syntax}:
8659
@code{RESULT = MCLOCK()}
8660
 
8661
@item @emph{Return value}:
8662
The return value is a scalar of type @code{INTEGER(4)}, equal to the
8663
number of clock ticks since the start of the process, or @code{-1} if
8664
the system does not support @code{clock(3)}.
8665
 
8666
@item @emph{See also}:
8667
@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8668
 
8669
@end table
8670
 
8671
 
8672
 
8673
@node MCLOCK8
8674
@section @code{MCLOCK8} --- Time function (64-bit)
8675
@fnindex MCLOCK8
8676
@cindex time, clock ticks
8677
@cindex clock ticks
8678
 
8679
@table @asis
8680
@item @emph{Description}:
8681
Returns the number of clock ticks since the start of the process, based
8682
on the function @code{clock(3)} in the C standard library.
8683
 
8684
@emph{Warning:} this intrinsic does not increase the range of the timing
8685
values over that returned by @code{clock(3)}. On a system with a 32-bit
8686
@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8687
it is converted to a 64-bit @code{INTEGER(8)} value. That means
8688
overflows of the 32-bit value can still occur. Therefore, the values
8689
returned by this intrinsic might be or become negative or numerically
8690
less than previous values during a single run of the compiled program.
8691
 
8692
@item @emph{Standard}:
8693
GNU extension
8694
 
8695
@item @emph{Class}:
8696
Function
8697
 
8698
@item @emph{Syntax}:
8699
@code{RESULT = MCLOCK8()}
8700
 
8701
@item @emph{Return value}:
8702
The return value is a scalar of type @code{INTEGER(8)}, equal to the
8703
number of clock ticks since the start of the process, or @code{-1} if
8704
the system does not support @code{clock(3)}.
8705
 
8706
@item @emph{See also}:
8707
@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8708
 
8709
@end table
8710
 
8711
 
8712
 
8713
@node MERGE
8714
@section @code{MERGE} --- Merge variables
8715
@fnindex MERGE
8716
@cindex array, merge arrays
8717
@cindex array, combine arrays
8718
 
8719
@table @asis
8720
@item @emph{Description}:
8721
Select values from two arrays according to a logical mask.  The result
8722
is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8723
@var{FSOURCE} if it is @code{.FALSE.}.
8724
 
8725
@item @emph{Standard}:
8726
Fortran 95 and later
8727
 
8728
@item @emph{Class}:
8729
Elemental function
8730
 
8731
@item @emph{Syntax}:
8732
@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8733
 
8734
@item @emph{Arguments}:
8735
@multitable @columnfractions .15 .70
8736
@item @var{TSOURCE} @tab May be of any type.
8737
@item @var{FSOURCE} @tab Shall be of the same type and type parameters
8738
as @var{TSOURCE}.
8739
@item @var{MASK}    @tab Shall be of type @code{LOGICAL}.
8740
@end multitable
8741
 
8742
@item @emph{Return value}:
8743
The result is of the same type and type parameters as @var{TSOURCE}.
8744
 
8745
@end table
8746
 
8747
 
8748
 
8749
@node MERGE_BITS
8750
@section @code{MERGE_BITS} --- Merge of bits under mask
8751
@fnindex MERGE_BITS
8752
@cindex bits, merge
8753
 
8754
@table @asis
8755
@item @emph{Description}:
8756
@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8757
as determined by the mask.  The i-th bit of the result is equal to the
8758
i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8759
the i-th bit of @var{J} otherwise.
8760
 
8761
@item @emph{Standard}:
8762
Fortran 2008 and later
8763
 
8764
@item @emph{Class}:
8765
Elemental function
8766
 
8767
@item @emph{Syntax}:
8768
@code{RESULT = MERGE_BITS(I, J, MASK)}
8769
 
8770
@item @emph{Arguments}:
8771
@multitable @columnfractions .15 .70
8772
@item @var{I}    @tab Shall be of type @code{INTEGER}.
8773
@item @var{J}    @tab Shall be of type @code{INTEGER} and of the same
8774
kind as @var{I}.
8775
@item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8776
kind as @var{I}.
8777
@end multitable
8778
 
8779
@item @emph{Return value}:
8780
The result is of the same type and kind as @var{I}.
8781
 
8782
@end table
8783
 
8784
 
8785
 
8786
@node MIN
8787
@section @code{MIN} --- Minimum value of an argument list
8788
@fnindex MIN
8789
@fnindex MIN0
8790
@fnindex AMIN0
8791
@fnindex MIN1
8792
@fnindex AMIN1
8793
@fnindex DMIN1
8794
@cindex minimum value
8795
 
8796
@table @asis
8797
@item @emph{Description}:
8798
Returns the argument with the smallest (most negative) value.
8799
 
8800
@item @emph{Standard}:
8801
Fortran 77 and later
8802
 
8803
@item @emph{Class}:
8804
Elemental function
8805
 
8806
@item @emph{Syntax}:
8807
@code{RESULT = MIN(A1, A2 [, A3, ...])}
8808
 
8809
@item @emph{Arguments}:
8810
@multitable @columnfractions .15 .70
8811
@item @var{A1}          @tab The type shall be @code{INTEGER} or
8812
@code{REAL}.
8813
@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8814
as @var{A1}.  (As a GNU extension, arguments of different kinds are
8815
permitted.)
8816
@end multitable
8817
 
8818
@item @emph{Return value}:
8819
The return value corresponds to the maximum value among the arguments,
8820
and has the same type and kind as the first argument.
8821
 
8822
@item @emph{Specific names}:
8823
@multitable @columnfractions .20 .20 .20 .25
8824
@item Name              @tab Argument             @tab Return type        @tab Standard
8825
@item @code{MIN0(A1)}   @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8826
@item @code{AMIN0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{REAL(4)}     @tab Fortran 77 and later
8827
@item @code{MIN1(A1)}   @tab @code{REAL A1}       @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8828
@item @code{AMIN1(A1)}  @tab @code{REAL(4) A1}    @tab @code{REAL(4)}     @tab Fortran 77 and later
8829
@item @code{DMIN1(A1)}  @tab @code{REAL(8) A1}    @tab @code{REAL(8)}     @tab Fortran 77 and later
8830
@end multitable
8831
 
8832
@item @emph{See also}:
8833
@ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8834
@end table
8835
 
8836
 
8837
 
8838
@node MINEXPONENT
8839
@section @code{MINEXPONENT} --- Minimum exponent of a real kind
8840
@fnindex MINEXPONENT
8841
@cindex model representation, minimum exponent
8842
 
8843
@table @asis
8844
@item @emph{Description}:
8845
@code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8846
type of @code{X}.
8847
 
8848
@item @emph{Standard}:
8849
Fortran 95 and later
8850
 
8851
@item @emph{Class}:
8852
Inquiry function
8853
 
8854
@item @emph{Syntax}:
8855
@code{RESULT = MINEXPONENT(X)}
8856
 
8857
@item @emph{Arguments}:
8858
@multitable @columnfractions .15 .70
8859
@item @var{X} @tab Shall be of type @code{REAL}.
8860
@end multitable
8861
 
8862
@item @emph{Return value}:
8863
The return value is of type @code{INTEGER} and of the default integer
8864
kind.
8865
 
8866
@item @emph{Example}:
8867
See @code{MAXEXPONENT} for an example.
8868
@end table
8869
 
8870
 
8871
 
8872
@node MINLOC
8873
@section @code{MINLOC} --- Location of the minimum value within an array
8874
@fnindex MINLOC
8875
@cindex array, location of minimum element
8876
 
8877
@table @asis
8878
@item @emph{Description}:
8879
Determines the location of the element in the array with the minimum
8880
value, or, if the @var{DIM} argument is supplied, determines the
8881
locations of the minimum element along each row of the array in the
8882
@var{DIM} direction.  If @var{MASK} is present, only the elements for
8883
which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8884
element in the array has the minimum value, the location returned is
8885
that of the first such element in array element order.  If the array has
8886
zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8887
the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8888
and all of the elements of @var{MASK} along a given row are zero, the
8889
result value for that row is zero.
8890
 
8891
@item @emph{Standard}:
8892
Fortran 95 and later
8893
 
8894
@item @emph{Class}:
8895
Transformational function
8896
 
8897
@item @emph{Syntax}:
8898
@multitable @columnfractions .80
8899
@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8900
@item @code{RESULT = MINLOC(ARRAY [, MASK])}
8901
@end multitable
8902
 
8903
@item @emph{Arguments}:
8904
@multitable @columnfractions .15 .70
8905
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8906
@code{REAL}.
8907
@item @var{DIM}   @tab (Optional) Shall be a scalar of type
8908
@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8909
inclusive.  It may not be an optional dummy argument.
8910
@item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8911
and conformable with @var{ARRAY}.
8912
@end multitable
8913
 
8914
@item @emph{Return value}:
8915
If @var{DIM} is absent, the result is a rank-one array with a length
8916
equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8917
is an array with a rank one less than the rank of @var{ARRAY}, and a
8918
size corresponding to the size of @var{ARRAY} with the @var{DIM}
8919
dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8920
of one, the result is a scalar.  In all cases, the result is of default
8921
@code{INTEGER} type.
8922
 
8923
@item @emph{See also}:
8924
@ref{MIN}, @ref{MINVAL}
8925
 
8926
@end table
8927
 
8928
 
8929
 
8930
@node MINVAL
8931
@section @code{MINVAL} --- Minimum value of an array
8932
@fnindex MINVAL
8933
@cindex array, minimum value
8934
@cindex minimum value
8935
 
8936
@table @asis
8937
@item @emph{Description}:
8938
Determines the minimum value of the elements in an array value, or, if
8939
the @var{DIM} argument is supplied, determines the minimum value along
8940
each row of the array in the @var{DIM} direction.  If @var{MASK} is
8941
present, only the elements for which @var{MASK} is @code{.TRUE.} are
8942
considered.  If the array has zero size, or all of the elements of
8943
@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8944
@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8945
@var{ARRAY} is of character type.
8946
 
8947
@item @emph{Standard}:
8948
Fortran 95 and later
8949
 
8950
@item @emph{Class}:
8951
Transformational function
8952
 
8953
@item @emph{Syntax}:
8954
@multitable @columnfractions .80
8955
@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8956
@item @code{RESULT = MINVAL(ARRAY [, MASK])}
8957
@end multitable
8958
 
8959
@item @emph{Arguments}:
8960
@multitable @columnfractions .15 .70
8961
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8962
@code{REAL}.
8963
@item @var{DIM}   @tab (Optional) Shall be a scalar of type
8964
@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8965
inclusive.  It may not be an optional dummy argument.
8966
@item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8967
and conformable with @var{ARRAY}.
8968
@end multitable
8969
 
8970
@item @emph{Return value}:
8971
If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8972
is a scalar.  If @var{DIM} is present, the result is an array with a
8973
rank one less than the rank of @var{ARRAY}, and a size corresponding to
8974
the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8975
cases, the result is of the same type and kind as @var{ARRAY}.
8976
 
8977
@item @emph{See also}:
8978
@ref{MIN}, @ref{MINLOC}
8979
 
8980
@end table
8981
 
8982
 
8983
 
8984
@node MOD
8985
@section @code{MOD} --- Remainder function
8986
@fnindex MOD
8987
@fnindex AMOD
8988
@fnindex DMOD
8989
@cindex remainder
8990
@cindex division, remainder
8991
 
8992
@table @asis
8993
@item @emph{Description}:
8994
@code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8995
calculated as @code{A - (INT(A/P) * P)}.
8996
 
8997
@item @emph{Standard}:
8998
Fortran 77 and later
8999
 
9000
@item @emph{Class}:
9001
Elemental function
9002
 
9003
@item @emph{Syntax}:
9004
@code{RESULT = MOD(A, P)}
9005
 
9006
@item @emph{Arguments}:
9007
@multitable @columnfractions .15 .70
9008
@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9009
@item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
9010
equal to zero
9011
@end multitable
9012
 
9013
@item @emph{Return value}:
9014
The kind of the return value is the result of cross-promoting
9015
the kinds of the arguments.
9016
 
9017
@item @emph{Example}:
9018
@smallexample
9019
program test_mod
9020
  print *, mod(17,3)
9021
  print *, mod(17.5,5.5)
9022
  print *, mod(17.5d0,5.5)
9023
  print *, mod(17.5,5.5d0)
9024
 
9025
  print *, mod(-17,3)
9026
  print *, mod(-17.5,5.5)
9027
  print *, mod(-17.5d0,5.5)
9028
  print *, mod(-17.5,5.5d0)
9029
 
9030
  print *, mod(17,-3)
9031
  print *, mod(17.5,-5.5)
9032
  print *, mod(17.5d0,-5.5)
9033
  print *, mod(17.5,-5.5d0)
9034
end program test_mod
9035
@end smallexample
9036
 
9037
@item @emph{Specific names}:
9038
@multitable @columnfractions .20 .20 .20 .25
9039
@item Name             @tab Arguments          @tab Return type    @tab Standard
9040
@item @code{MOD(A,P)}  @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9041
@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9042
@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9043
@end multitable
9044
@end table
9045
 
9046
 
9047
 
9048
@node MODULO
9049
@section @code{MODULO} --- Modulo function
9050
@fnindex MODULO
9051
@cindex modulo
9052
@cindex division, modulo
9053
 
9054
@table @asis
9055
@item @emph{Description}:
9056
@code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9057
 
9058
@item @emph{Standard}:
9059
Fortran 95 and later
9060
 
9061
@item @emph{Class}:
9062
Elemental function
9063
 
9064
@item @emph{Syntax}:
9065
@code{RESULT = MODULO(A, P)}
9066
 
9067
@item @emph{Arguments}:
9068
@multitable @columnfractions .15 .70
9069
@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9070
@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9071
@end multitable
9072
 
9073
@item @emph{Return value}:
9074
The type and kind of the result are those of the arguments.
9075
@table @asis
9076
@item If @var{A} and @var{P} are of type @code{INTEGER}:
9077
@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9078
@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9079
(exclusive).
9080
@item If @var{A} and @var{P} are of type @code{REAL}:
9081
@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9082
@end table
9083
In all cases, if @var{P} is zero the result is processor-dependent.
9084
 
9085
@item @emph{Example}:
9086
@smallexample
9087
program test_modulo
9088
  print *, modulo(17,3)
9089
  print *, modulo(17.5,5.5)
9090
 
9091
  print *, modulo(-17,3)
9092
  print *, modulo(-17.5,5.5)
9093
 
9094
  print *, modulo(17,-3)
9095
  print *, modulo(17.5,-5.5)
9096
end program
9097
@end smallexample
9098
 
9099
@end table
9100
 
9101
 
9102
 
9103
@node MOVE_ALLOC
9104
@section @code{MOVE_ALLOC} --- Move allocation from one object to another
9105
@fnindex MOVE_ALLOC
9106
@cindex moving allocation
9107
@cindex allocation, moving
9108
 
9109
@table @asis
9110
@item @emph{Description}:
9111
@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9112
@var{TO}.  @var{FROM} will become deallocated in the process.
9113
 
9114
@item @emph{Standard}:
9115
Fortran 2003 and later
9116
 
9117
@item @emph{Class}:
9118
Pure subroutine
9119
 
9120
@item @emph{Syntax}:
9121
@code{CALL MOVE_ALLOC(FROM, TO)}
9122
 
9123
@item @emph{Arguments}:
9124
@multitable @columnfractions .15 .70
9125
@item @var{FROM}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9126
of any type and kind.
9127
@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9128
of the same type, kind and rank as @var{FROM}.
9129
@end multitable
9130
 
9131
@item @emph{Return value}:
9132
None
9133
 
9134
@item @emph{Example}:
9135
@smallexample
9136
program test_move_alloc
9137
    integer, allocatable :: a(:), b(:)
9138
 
9139
    allocate(a(3))
9140
    a = [ 1, 2, 3 ]
9141
    call move_alloc(a, b)
9142
    print *, allocated(a), allocated(b)
9143
    print *, b
9144
end program test_move_alloc
9145
@end smallexample
9146
@end table
9147
 
9148
 
9149
 
9150
@node MVBITS
9151
@section @code{MVBITS} --- Move bits from one integer to another
9152
@fnindex MVBITS
9153
@cindex bits, move
9154
 
9155
@table @asis
9156
@item @emph{Description}:
9157
Moves @var{LEN} bits from positions @var{FROMPOS} through
9158
@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9159
@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9160
affected by the movement of bits is unchanged. The values of
9161
@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9162
@code{BIT_SIZE(FROM)}.
9163
 
9164
@item @emph{Standard}:
9165
Fortran 95 and later
9166
 
9167
@item @emph{Class}:
9168
Elemental subroutine
9169
 
9170
@item @emph{Syntax}:
9171
@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9172
 
9173
@item @emph{Arguments}:
9174
@multitable @columnfractions .15 .70
9175
@item @var{FROM}    @tab The type shall be @code{INTEGER}.
9176
@item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9177
@item @var{LEN}     @tab The type shall be @code{INTEGER}.
9178
@item @var{TO}      @tab The type shall be @code{INTEGER}, of the
9179
same kind as @var{FROM}.
9180
@item @var{TOPOS}   @tab The type shall be @code{INTEGER}.
9181
@end multitable
9182
 
9183
@item @emph{See also}:
9184
@ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9185
@end table
9186
 
9187
 
9188
 
9189
@node NEAREST
9190
@section @code{NEAREST} --- Nearest representable number
9191
@fnindex NEAREST
9192
@cindex real number, nearest different
9193
@cindex floating point, nearest different
9194
 
9195
@table @asis
9196
@item @emph{Description}:
9197
@code{NEAREST(X, S)} returns the processor-representable number nearest
9198
to @code{X} in the direction indicated by the sign of @code{S}.
9199
 
9200
@item @emph{Standard}:
9201
Fortran 95 and later
9202
 
9203
@item @emph{Class}:
9204
Elemental function
9205
 
9206
@item @emph{Syntax}:
9207
@code{RESULT = NEAREST(X, S)}
9208
 
9209
@item @emph{Arguments}:
9210
@multitable @columnfractions .15 .70
9211
@item @var{X} @tab Shall be of type @code{REAL}.
9212
@item @var{S} @tab (Optional) shall be of type @code{REAL} and
9213
not equal to zero.
9214
@end multitable
9215
 
9216
@item @emph{Return value}:
9217
The return value is of the same type as @code{X}. If @code{S} is
9218
positive, @code{NEAREST} returns the processor-representable number
9219
greater than @code{X} and nearest to it. If @code{S} is negative,
9220
@code{NEAREST} returns the processor-representable number smaller than
9221
@code{X} and nearest to it.
9222
 
9223
@item @emph{Example}:
9224
@smallexample
9225
program test_nearest
9226
  real :: x, y
9227
  x = nearest(42.0, 1.0)
9228
  y = nearest(42.0, -1.0)
9229
  write (*,"(3(G20.15))") x, y, x - y
9230
end program test_nearest
9231
@end smallexample
9232
@end table
9233
 
9234
 
9235
 
9236
@node NEW_LINE
9237
@section @code{NEW_LINE} --- New line character
9238
@fnindex NEW_LINE
9239
@cindex newline
9240
@cindex output, newline
9241
 
9242
@table @asis
9243
@item @emph{Description}:
9244
@code{NEW_LINE(C)} returns the new-line character.
9245
 
9246
@item @emph{Standard}:
9247
Fortran 2003 and later
9248
 
9249
@item @emph{Class}:
9250
Inquiry function
9251
 
9252
@item @emph{Syntax}:
9253
@code{RESULT = NEW_LINE(C)}
9254
 
9255
@item @emph{Arguments}:
9256
@multitable @columnfractions .15 .70
9257
@item @var{C}    @tab The argument shall be a scalar or array of the
9258
type @code{CHARACTER}.
9259
@end multitable
9260
 
9261
@item @emph{Return value}:
9262
Returns a @var{CHARACTER} scalar of length one with the new-line character of
9263
the same kind as parameter @var{C}.
9264
 
9265
@item @emph{Example}:
9266
@smallexample
9267
program newline
9268
  implicit none
9269
  write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9270
end program newline
9271
@end smallexample
9272
@end table
9273
 
9274
 
9275
 
9276
@node NINT
9277
@section @code{NINT} --- Nearest whole number
9278
@fnindex NINT
9279
@fnindex IDNINT
9280
@cindex rounding, nearest whole number
9281
 
9282
@table @asis
9283
@item @emph{Description}:
9284
@code{NINT(A)} rounds its argument to the nearest whole number.
9285
 
9286
@item @emph{Standard}:
9287
Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9288
 
9289
@item @emph{Class}:
9290
Elemental function
9291
 
9292
@item @emph{Syntax}:
9293
@code{RESULT = NINT(A [, KIND])}
9294
 
9295
@item @emph{Arguments}:
9296
@multitable @columnfractions .15 .70
9297
@item @var{A}    @tab The type of the argument shall be @code{REAL}.
9298
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9299
expression indicating the kind parameter of the result.
9300
@end multitable
9301
 
9302
@item @emph{Return value}:
9303
Returns @var{A} with the fractional portion of its magnitude eliminated by
9304
rounding to the nearest whole number and with its sign preserved,
9305
converted to an @code{INTEGER} of the default kind.
9306
 
9307
@item @emph{Example}:
9308
@smallexample
9309
program test_nint
9310
  real(4) x4
9311
  real(8) x8
9312
  x4 = 1.234E0_4
9313
  x8 = 4.321_8
9314
  print *, nint(x4), idnint(x8)
9315
end program test_nint
9316
@end smallexample
9317
 
9318
@item @emph{Specific names}:
9319
@multitable @columnfractions .20 .20 .20 .25
9320
@item Name             @tab Argument           @tab Return Type     @tab Standard
9321
@item @code{NINT(A)}   @tab @code{REAL(4) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9322
@item @code{IDNINT(A)} @tab @code{REAL(8) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9323
@end multitable
9324
 
9325
@item @emph{See also}:
9326
@ref{CEILING}, @ref{FLOOR}
9327
 
9328
@end table
9329
 
9330
 
9331
 
9332
@node NORM2
9333
@section @code{NORM2} --- Euclidean vector norms
9334
@fnindex NORM2
9335
@cindex Euclidean vector norm
9336
@cindex L2 vector norm
9337
@cindex norm, Euclidean
9338
 
9339
@table @asis
9340
@item @emph{Description}:
9341
Calculates the Euclidean vector norm (@math{L_2} norm) of
9342
of @var{ARRAY} along dimension @var{DIM}.
9343
 
9344
@item @emph{Standard}:
9345
Fortran 2008 and later
9346
 
9347
@item @emph{Class}:
9348
Transformational function
9349
 
9350
@item @emph{Syntax}:
9351
@multitable @columnfractions .80
9352
@item @code{RESULT = NORM2(ARRAY[, DIM])}
9353
@end multitable
9354
 
9355
@item @emph{Arguments}:
9356
@multitable @columnfractions .15 .70
9357
@item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9358
@item @var{DIM}   @tab (Optional) shall be a scalar of type
9359
@code{INTEGER} with a value in the range from 1 to n, where n
9360
equals the rank of @var{ARRAY}.
9361
@end multitable
9362
 
9363
@item @emph{Return value}:
9364
The result is of the same type as @var{ARRAY}.
9365
 
9366
If @var{DIM} is absent, a scalar with the square root of the sum of all
9367
elements in @var{ARRAY} squared  is returned. Otherwise, an array of
9368
rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9369
shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9370
is returned.
9371
 
9372
@item @emph{Example}:
9373
@smallexample
9374
PROGRAM test_sum
9375
  REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9376
  print *, NORM2(x)  ! = sqrt(55.) ~ 7.416
9377
END PROGRAM
9378
@end smallexample
9379
@end table
9380
 
9381
 
9382
 
9383
@node NOT
9384
@section @code{NOT} --- Logical negation
9385
@fnindex NOT
9386
@cindex bits, negate
9387
@cindex bitwise logical not
9388
@cindex logical not, bitwise
9389
 
9390
@table @asis
9391
@item @emph{Description}:
9392
@code{NOT} returns the bitwise Boolean inverse of @var{I}.
9393
 
9394
@item @emph{Standard}:
9395
Fortran 95 and later
9396
 
9397
@item @emph{Class}:
9398
Elemental function
9399
 
9400
@item @emph{Syntax}:
9401
@code{RESULT = NOT(I)}
9402
 
9403
@item @emph{Arguments}:
9404
@multitable @columnfractions .15 .70
9405
@item @var{I} @tab The type shall be @code{INTEGER}.
9406
@end multitable
9407
 
9408
@item @emph{Return value}:
9409
The return type is @code{INTEGER}, of the same kind as the
9410
argument.
9411
 
9412
@item @emph{See also}:
9413
@ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9414
 
9415
@end table
9416
 
9417
 
9418
 
9419
@node NULL
9420
@section @code{NULL} --- Function that returns an disassociated pointer
9421
@fnindex NULL
9422
@cindex pointer, status
9423
@cindex pointer, disassociated
9424
 
9425
@table @asis
9426
@item @emph{Description}:
9427
Returns a disassociated pointer.
9428
 
9429
If @var{MOLD} is present, a disassociated pointer of the same type is
9430
returned, otherwise the type is determined by context.
9431
 
9432
In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9433
includes cases where it is required.
9434
 
9435
@item @emph{Standard}:
9436
Fortran 95 and later
9437
 
9438
@item @emph{Class}:
9439
Transformational function
9440
 
9441
@item @emph{Syntax}:
9442
@code{PTR => NULL([MOLD])}
9443
 
9444
@item @emph{Arguments}:
9445
@multitable @columnfractions .15 .70
9446
@item @var{MOLD} @tab (Optional) shall be a pointer of any association
9447
status and of any type.
9448
@end multitable
9449
 
9450
@item @emph{Return value}:
9451
A disassociated pointer.
9452
 
9453
@item @emph{Example}:
9454
@smallexample
9455
REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9456
@end smallexample
9457
 
9458
@item @emph{See also}:
9459
@ref{ASSOCIATED}
9460
@end table
9461
 
9462
 
9463
 
9464
@node NUM_IMAGES
9465
@section @code{NUM_IMAGES} --- Function that returns the number of images
9466
@fnindex NUM_IMAGES
9467
@cindex coarray, @code{NUM_IMAGES}
9468
@cindex images, number of
9469
 
9470
@table @asis
9471
@item @emph{Description}:
9472
Returns the number of images.
9473
 
9474
@item @emph{Standard}:
9475
Fortran 2008 and later
9476
 
9477
@item @emph{Class}:
9478
Transformational function
9479
 
9480
@item @emph{Syntax}:
9481
@code{RESULT = NUM_IMAGES()}
9482
 
9483
@item @emph{Arguments}: None.
9484
 
9485
@item @emph{Return value}:
9486
Scalar default-kind integer.
9487
 
9488
@item @emph{Example}:
9489
@smallexample
9490
INTEGER :: value[*]
9491
INTEGER :: i
9492
value = THIS_IMAGE()
9493
SYNC ALL
9494
IF (THIS_IMAGE() == 1) THEN
9495
  DO i = 1, NUM_IMAGES()
9496
    WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9497
  END DO
9498
END IF
9499
@end smallexample
9500
 
9501
@item @emph{See also}:
9502
@ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9503
@end table
9504
 
9505
 
9506
 
9507
@node OR
9508
@section @code{OR} --- Bitwise logical OR
9509
@fnindex OR
9510
@cindex bitwise logical or
9511
@cindex logical or, bitwise
9512
 
9513
@table @asis
9514
@item @emph{Description}:
9515
Bitwise logical @code{OR}.
9516
 
9517
This intrinsic routine is provided for backwards compatibility with
9518
GNU Fortran 77.  For integer arguments, programmers should consider
9519
the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9520
 
9521
@item @emph{Standard}:
9522
GNU extension
9523
 
9524
@item @emph{Class}:
9525
Function
9526
 
9527
@item @emph{Syntax}:
9528
@code{RESULT = OR(I, J)}
9529
 
9530
@item @emph{Arguments}:
9531
@multitable @columnfractions .15 .70
9532
@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9533
type or a scalar @code{LOGICAL} type.
9534
@item @var{J} @tab The type shall be the same as the type of @var{J}.
9535
@end multitable
9536
 
9537
@item @emph{Return value}:
9538
The return type is either a scalar @code{INTEGER} or a scalar
9539
@code{LOGICAL}.  If the kind type parameters differ, then the
9540
smaller kind type is implicitly converted to larger kind, and the
9541
return has the larger kind.
9542
 
9543
@item @emph{Example}:
9544
@smallexample
9545
PROGRAM test_or
9546
  LOGICAL :: T = .TRUE., F = .FALSE.
9547
  INTEGER :: a, b
9548
  DATA a / Z'F' /, b / Z'3' /
9549
 
9550
  WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9551
  WRITE (*,*) OR(a, b)
9552
END PROGRAM
9553
@end smallexample
9554
 
9555
@item @emph{See also}:
9556
Fortran 95 elemental function: @ref{IOR}
9557
@end table
9558
 
9559
 
9560
 
9561
@node PACK
9562
@section @code{PACK} --- Pack an array into an array of rank one
9563
@fnindex PACK
9564
@cindex array, packing
9565
@cindex array, reduce dimension
9566
@cindex array, gather elements
9567
 
9568
@table @asis
9569
@item @emph{Description}:
9570
Stores the elements of @var{ARRAY} in an array of rank one.
9571
 
9572
The beginning of the resulting array is made up of elements whose @var{MASK}
9573
equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9574
@var{VECTOR}.
9575
 
9576
@item @emph{Standard}:
9577
Fortran 95 and later
9578
 
9579
@item @emph{Class}:
9580
Transformational function
9581
 
9582
@item @emph{Syntax}:
9583
@code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9584
 
9585
@item @emph{Arguments}:
9586
@multitable @columnfractions .15 .70
9587
@item @var{ARRAY}  @tab Shall be an array of any type.
9588
@item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and
9589
of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9590
scalar.
9591
@item @var{VECTOR} @tab (Optional) shall be an array of the same type
9592
as @var{ARRAY} and of rank one. If present, the number of elements in
9593
@var{VECTOR} shall be equal to or greater than the number of true elements
9594
in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9595
@var{VECTOR} shall be equal to or greater than the number of elements in
9596
@var{ARRAY}.
9597
@end multitable
9598
 
9599
@item @emph{Return value}:
9600
The result is an array of rank one and the same type as that of @var{ARRAY}.
9601
If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9602
number of @code{TRUE} values in @var{MASK} otherwise.
9603
 
9604
@item @emph{Example}:
9605
Gathering nonzero elements from an array:
9606
@smallexample
9607
PROGRAM test_pack_1
9608
  INTEGER :: m(6)
9609
  m = (/ 1, 0, 0, 0, 5, 0 /)
9610
  WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
9611
END PROGRAM
9612
@end smallexample
9613
 
9614
Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9615
@smallexample
9616
PROGRAM test_pack_2
9617
  INTEGER :: m(4)
9618
  m = (/ 1, 0, 0, 2 /)
9619
  WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
9620
END PROGRAM
9621
@end smallexample
9622
 
9623
@item @emph{See also}:
9624
@ref{UNPACK}
9625
@end table
9626
 
9627
 
9628
 
9629
@node PARITY
9630
@section @code{PARITY} --- Reduction with exclusive OR
9631
@fnindex PARITY
9632
@cindex Parity
9633
@cindex Reduction, XOR
9634
@cindex XOR reduction
9635
 
9636
@table @asis
9637
@item @emph{Description}:
9638
Calculates the parity, i.e. the reduction using @code{.XOR.},
9639
of @var{MASK} along dimension @var{DIM}.
9640
 
9641
@item @emph{Standard}:
9642
Fortran 2008 and later
9643
 
9644
@item @emph{Class}:
9645
Transformational function
9646
 
9647
@item @emph{Syntax}:
9648
@multitable @columnfractions .80
9649
@item @code{RESULT = PARITY(MASK[, DIM])}
9650
@end multitable
9651
 
9652
@item @emph{Arguments}:
9653
@multitable @columnfractions .15 .70
9654
@item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9655
@item @var{DIM}   @tab (Optional) shall be a scalar of type
9656
@code{INTEGER} with a value in the range from 1 to n, where n
9657
equals the rank of @var{MASK}.
9658
@end multitable
9659
 
9660
@item @emph{Return value}:
9661
The result is of the same type as @var{MASK}.
9662
 
9663
If @var{DIM} is absent, a scalar with the parity of all elements in
9664
@var{MASK} is returned, i.e. true if an odd number of elements is
9665
@code{.true.} and false otherwise.  If @var{DIM} is present, an array
9666
of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9667
and a shape similar to that of @var{MASK} with dimension @var{DIM}
9668
dropped is returned.
9669
 
9670
@item @emph{Example}:
9671
@smallexample
9672
PROGRAM test_sum
9673
  LOGICAL :: x(2) = [ .true., .false. ]
9674
  print *, PARITY(x) ! prints "T" (true).
9675
END PROGRAM
9676
@end smallexample
9677
@end table
9678
 
9679
 
9680
 
9681
@node PERROR
9682
@section @code{PERROR} --- Print system error message
9683
@fnindex PERROR
9684
@cindex system, error handling
9685
 
9686
@table @asis
9687
@item @emph{Description}:
9688
Prints (on the C @code{stderr} stream) a newline-terminated error
9689
message corresponding to the last system error. This is prefixed by
9690
@var{STRING}, a colon and a space. See @code{perror(3)}.
9691
 
9692
@item @emph{Standard}:
9693
GNU extension
9694
 
9695
@item @emph{Class}:
9696
Subroutine
9697
 
9698
@item @emph{Syntax}:
9699
@code{CALL PERROR(STRING)}
9700
 
9701
@item @emph{Arguments}:
9702
@multitable @columnfractions .15 .70
9703
@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9704
default kind.
9705
@end multitable
9706
 
9707
@item @emph{See also}:
9708
@ref{IERRNO}
9709
@end table
9710
 
9711
 
9712
 
9713
@node PRECISION
9714
@section @code{PRECISION} --- Decimal precision of a real kind
9715
@fnindex PRECISION
9716
@cindex model representation, precision
9717
 
9718
@table @asis
9719
@item @emph{Description}:
9720
@code{PRECISION(X)} returns the decimal precision in the model of the
9721
type of @code{X}.
9722
 
9723
@item @emph{Standard}:
9724
Fortran 95 and later
9725
 
9726
@item @emph{Class}:
9727
Inquiry function
9728
 
9729
@item @emph{Syntax}:
9730
@code{RESULT = PRECISION(X)}
9731
 
9732
@item @emph{Arguments}:
9733
@multitable @columnfractions .15 .70
9734
@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9735
@end multitable
9736
 
9737
@item @emph{Return value}:
9738
The return value is of type @code{INTEGER} and of the default integer
9739
kind.
9740
 
9741
@item @emph{See also}:
9742
@ref{SELECTED_REAL_KIND}, @ref{RANGE}
9743
 
9744
@item @emph{Example}:
9745
@smallexample
9746
program prec_and_range
9747
  real(kind=4) :: x(2)
9748
  complex(kind=8) :: y
9749
 
9750
  print *, precision(x), range(x)
9751
  print *, precision(y), range(y)
9752
end program prec_and_range
9753
@end smallexample
9754
@end table
9755
 
9756
 
9757
 
9758
@node POPCNT
9759
@section @code{POPCNT} --- Number of bits set
9760
@fnindex POPCNT
9761
@cindex binary representation
9762
@cindex bits set
9763
 
9764
@table @asis
9765
@item @emph{Description}:
9766
@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9767
representation of @code{I}.
9768
 
9769
@item @emph{Standard}:
9770
Fortran 2008 and later
9771
 
9772
@item @emph{Class}:
9773
Elemental function
9774
 
9775
@item @emph{Syntax}:
9776
@code{RESULT = POPCNT(I)}
9777
 
9778
@item @emph{Arguments}:
9779
@multitable @columnfractions .15 .70
9780
@item @var{I} @tab Shall be of type @code{INTEGER}.
9781
@end multitable
9782
 
9783
@item @emph{Return value}:
9784
The return value is of type @code{INTEGER} and of the default integer
9785
kind.
9786
 
9787
@item @emph{See also}:
9788
@ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9789
 
9790
@item @emph{Example}:
9791
@smallexample
9792
program test_population
9793
  print *, popcnt(127),       poppar(127)
9794
  print *, popcnt(huge(0_4)), poppar(huge(0_4))
9795
  print *, popcnt(huge(0_8)), poppar(huge(0_8))
9796
end program test_population
9797
@end smallexample
9798
@end table
9799
 
9800
 
9801
@node POPPAR
9802
@section @code{POPPAR} --- Parity of the number of bits set
9803
@fnindex POPPAR
9804
@cindex binary representation
9805
@cindex parity
9806
 
9807
@table @asis
9808
@item @emph{Description}:
9809
@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9810
of the number of bits set ('1' bits) in the binary representation of
9811
@code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9812
and 1 for an odd number of '1' bits.
9813
 
9814
@item @emph{Standard}:
9815
Fortran 2008 and later
9816
 
9817
@item @emph{Class}:
9818
Elemental function
9819
 
9820
@item @emph{Syntax}:
9821
@code{RESULT = POPPAR(I)}
9822
 
9823
@item @emph{Arguments}:
9824
@multitable @columnfractions .15 .70
9825
@item @var{I} @tab Shall be of type @code{INTEGER}.
9826
@end multitable
9827
 
9828
@item @emph{Return value}:
9829
The return value is of type @code{INTEGER} and of the default integer
9830
kind.
9831
 
9832
@item @emph{See also}:
9833
@ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9834
 
9835
@item @emph{Example}:
9836
@smallexample
9837
program test_population
9838
  print *, popcnt(127),       poppar(127)
9839
  print *, popcnt(huge(0_4)), poppar(huge(0_4))
9840
  print *, popcnt(huge(0_8)), poppar(huge(0_8))
9841
end program test_population
9842
@end smallexample
9843
@end table
9844
 
9845
 
9846
 
9847
@node PRESENT
9848
@section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9849
@fnindex PRESENT
9850
 
9851
@table @asis
9852
@item @emph{Description}:
9853
Determines whether an optional dummy argument is present.
9854
 
9855
@item @emph{Standard}:
9856
Fortran 95 and later
9857
 
9858
@item @emph{Class}:
9859
Inquiry function
9860
 
9861
@item @emph{Syntax}:
9862
@code{RESULT = PRESENT(A)}
9863
 
9864
@item @emph{Arguments}:
9865
@multitable @columnfractions .15 .70
9866
@item @var{A} @tab May be of any type and may be a pointer, scalar or array
9867
value, or a dummy procedure. It shall be the name of an optional dummy argument
9868
accessible within the current subroutine or function.
9869
@end multitable
9870
 
9871
@item @emph{Return value}:
9872
Returns either @code{TRUE} if the optional argument @var{A} is present, or
9873
@code{FALSE} otherwise.
9874
 
9875
@item @emph{Example}:
9876
@smallexample
9877
PROGRAM test_present
9878
  WRITE(*,*) f(), f(42)      ! "F T"
9879
CONTAINS
9880
  LOGICAL FUNCTION f(x)
9881
    INTEGER, INTENT(IN), OPTIONAL :: x
9882
    f = PRESENT(x)
9883
  END FUNCTION
9884
END PROGRAM
9885
@end smallexample
9886
@end table
9887
 
9888
 
9889
 
9890
@node PRODUCT
9891
@section @code{PRODUCT} --- Product of array elements
9892
@fnindex PRODUCT
9893
@cindex array, product
9894
@cindex array, multiply elements
9895
@cindex array, conditionally multiply elements
9896
@cindex multiply array elements
9897
 
9898
@table @asis
9899
@item @emph{Description}:
9900
Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9901
the corresponding element in @var{MASK} is @code{TRUE}.
9902
 
9903
@item @emph{Standard}:
9904
Fortran 95 and later
9905
 
9906
@item @emph{Class}:
9907
Transformational function
9908
 
9909
@item @emph{Syntax}:
9910
@multitable @columnfractions .80
9911
@item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9912
@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9913
@end multitable
9914
 
9915
@item @emph{Arguments}:
9916
@multitable @columnfractions .15 .70
9917
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9918
@code{REAL} or @code{COMPLEX}.
9919
@item @var{DIM}   @tab (Optional) shall be a scalar of type
9920
@code{INTEGER} with a value in the range from 1 to n, where n
9921
equals the rank of @var{ARRAY}.
9922
@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
9923
and either be a scalar or an array of the same shape as @var{ARRAY}.
9924
@end multitable
9925
 
9926
@item @emph{Return value}:
9927
The result is of the same type as @var{ARRAY}.
9928
 
9929
If @var{DIM} is absent, a scalar with the product of all elements in
9930
@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9931
the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9932
dimension @var{DIM} dropped is returned.
9933
 
9934
 
9935
@item @emph{Example}:
9936
@smallexample
9937
PROGRAM test_product
9938
  INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9939
  print *, PRODUCT(x)                    ! all elements, product = 120
9940
  print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9941
END PROGRAM
9942
@end smallexample
9943
 
9944
@item @emph{See also}:
9945
@ref{SUM}
9946
@end table
9947
 
9948
 
9949
 
9950
@node RADIX
9951
@section @code{RADIX} --- Base of a model number
9952
@fnindex RADIX
9953
@cindex model representation, base
9954
@cindex model representation, radix
9955
 
9956
@table @asis
9957
@item @emph{Description}:
9958
@code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9959
 
9960
@item @emph{Standard}:
9961
Fortran 95 and later
9962
 
9963
@item @emph{Class}:
9964
Inquiry function
9965
 
9966
@item @emph{Syntax}:
9967
@code{RESULT = RADIX(X)}
9968
 
9969
@item @emph{Arguments}:
9970
@multitable @columnfractions .15 .70
9971
@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9972
@end multitable
9973
 
9974
@item @emph{Return value}:
9975
The return value is a scalar of type @code{INTEGER} and of the default
9976
integer kind.
9977
 
9978
@item @emph{See also}:
9979
@ref{SELECTED_REAL_KIND}
9980
 
9981
@item @emph{Example}:
9982
@smallexample
9983
program test_radix
9984
  print *, "The radix for the default integer kind is", radix(0)
9985
  print *, "The radix for the default real kind is", radix(0.0)
9986
end program test_radix
9987
@end smallexample
9988
 
9989
@end table
9990
 
9991
 
9992
 
9993
@node RAN
9994
@section @code{RAN} --- Real pseudo-random number
9995
@fnindex RAN
9996
@cindex random number generation
9997
 
9998
@table @asis
9999
@item @emph{Description}:
10000
For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
10001
provided as an alias for @code{RAND}.  See @ref{RAND} for complete
10002
documentation.
10003
 
10004
@item @emph{Standard}:
10005
GNU extension
10006
 
10007
@item @emph{Class}:
10008
Function
10009
 
10010
@item @emph{See also}:
10011
@ref{RAND}, @ref{RANDOM_NUMBER}
10012
@end table
10013
 
10014
 
10015
 
10016
@node RAND
10017
@section @code{RAND} --- Real pseudo-random number
10018
@fnindex RAND
10019
@cindex random number generation
10020
 
10021
@table @asis
10022
@item @emph{Description}:
10023
@code{RAND(FLAG)} returns a pseudo-random number from a uniform
10024
distribution between 0 and 1. If @var{FLAG} is 0, the next number
10025
in the current sequence is returned; if @var{FLAG} is 1, the generator
10026
is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10027
it is used as a new seed with @code{SRAND}.
10028
 
10029
This intrinsic routine is provided for backwards compatibility with
10030
GNU Fortran 77. It implements a simple modulo generator as provided
10031
by @command{g77}. For new code, one should consider the use of
10032
@ref{RANDOM_NUMBER} as it implements a superior algorithm.
10033
 
10034
@item @emph{Standard}:
10035
GNU extension
10036
 
10037
@item @emph{Class}:
10038
Function
10039
 
10040
@item @emph{Syntax}:
10041
@code{RESULT = RAND(I)}
10042
 
10043
@item @emph{Arguments}:
10044
@multitable @columnfractions .15 .70
10045
@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10046
@end multitable
10047
 
10048
@item @emph{Return value}:
10049
The return value is of @code{REAL} type and the default kind.
10050
 
10051
@item @emph{Example}:
10052
@smallexample
10053
program test_rand
10054
  integer,parameter :: seed = 86456
10055
 
10056
  call srand(seed)
10057
  print *, rand(), rand(), rand(), rand()
10058
  print *, rand(seed), rand(), rand(), rand()
10059
end program test_rand
10060
@end smallexample
10061
 
10062
@item @emph{See also}:
10063
@ref{SRAND}, @ref{RANDOM_NUMBER}
10064
 
10065
@end table
10066
 
10067
 
10068
 
10069
@node RANDOM_NUMBER
10070
@section @code{RANDOM_NUMBER} --- Pseudo-random number
10071
@fnindex RANDOM_NUMBER
10072
@cindex random number generation
10073
 
10074
@table @asis
10075
@item @emph{Description}:
10076
Returns a single pseudorandom number or an array of pseudorandom numbers
10077
from the uniform distribution over the range @math{ 0 \leq x < 1}.
10078
 
10079
The runtime-library implements George Marsaglia's KISS (Keep It Simple
10080
Stupid) random number generator (RNG). This RNG combines:
10081
@enumerate
10082
@item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10083
with a period of @math{2^{32}},
10084
@item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10085
@item  Two 16-bit multiply-with-carry generators with a period of
10086
@math{597273182964842497 > 2^{59}}.
10087
@end enumerate
10088
The overall period exceeds @math{2^{123}}.
10089
 
10090
Please note, this RNG is thread safe if used within OpenMP directives,
10091
i.e., its state will be consistent while called from multiple threads.
10092
However, the KISS generator does not create random numbers in parallel
10093
from multiple sources, but in sequence from a single source. If an
10094
OpenMP-enabled application heavily relies on random numbers, one should
10095
consider employing a dedicated parallel random number generator instead.
10096
 
10097
@item @emph{Standard}:
10098
Fortran 95 and later
10099
 
10100
@item @emph{Class}:
10101
Subroutine
10102
 
10103
@item @emph{Syntax}:
10104
@code{RANDOM_NUMBER(HARVEST)}
10105
 
10106
@item @emph{Arguments}:
10107
@multitable @columnfractions .15 .70
10108
@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10109
@end multitable
10110
 
10111
@item @emph{Example}:
10112
@smallexample
10113
program test_random_number
10114
  REAL :: r(5,5)
10115
  CALL init_random_seed()         ! see example of RANDOM_SEED
10116
  CALL RANDOM_NUMBER(r)
10117
end program
10118
@end smallexample
10119
 
10120
@item @emph{See also}:
10121
@ref{RANDOM_SEED}
10122
@end table
10123
 
10124
 
10125
 
10126
@node RANDOM_SEED
10127
@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10128
@fnindex RANDOM_SEED
10129
@cindex random number generation, seeding
10130
@cindex seeding a random number generator
10131
 
10132
@table @asis
10133
@item @emph{Description}:
10134
Restarts or queries the state of the pseudorandom number generator used by
10135
@code{RANDOM_NUMBER}.
10136
 
10137
If @code{RANDOM_SEED} is called without arguments, it is initialized to
10138
a default state. The example below shows how to initialize the random
10139
seed based on the system's time.
10140
 
10141
@item @emph{Standard}:
10142
Fortran 95 and later
10143
 
10144
@item @emph{Class}:
10145
Subroutine
10146
 
10147
@item @emph{Syntax}:
10148
@code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10149
 
10150
@item @emph{Arguments}:
10151
@multitable @columnfractions .15 .70
10152
@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10153
@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10154
of the arrays used with the @var{PUT} and @var{GET} arguments.
10155
@item @var{PUT}  @tab (Optional) Shall be an array of type default
10156
@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10157
the array must be larger than or equal to the number returned by the
10158
@var{SIZE} argument.
10159
@item @var{GET}  @tab (Optional) Shall be an array of type default
10160
@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10161
of the array must be larger than or equal to the number returned by
10162
the @var{SIZE} argument.
10163
@end multitable
10164
 
10165
@item @emph{Example}:
10166
@smallexample
10167
SUBROUTINE init_random_seed()
10168
  INTEGER :: i, n, clock
10169
  INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10170
 
10171
  CALL RANDOM_SEED(size = n)
10172
  ALLOCATE(seed(n))
10173
 
10174
  CALL SYSTEM_CLOCK(COUNT=clock)
10175
 
10176
  seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10177
  CALL RANDOM_SEED(PUT = seed)
10178
 
10179
  DEALLOCATE(seed)
10180
END SUBROUTINE
10181
@end smallexample
10182
 
10183
@item @emph{See also}:
10184
@ref{RANDOM_NUMBER}
10185
@end table
10186
 
10187
 
10188
 
10189
@node RANGE
10190
@section @code{RANGE} --- Decimal exponent range
10191
@fnindex RANGE
10192
@cindex model representation, range
10193
 
10194
@table @asis
10195
@item @emph{Description}:
10196
@code{RANGE(X)} returns the decimal exponent range in the model of the
10197
type of @code{X}.
10198
 
10199
@item @emph{Standard}:
10200
Fortran 95 and later
10201
 
10202
@item @emph{Class}:
10203
Inquiry function
10204
 
10205
@item @emph{Syntax}:
10206
@code{RESULT = RANGE(X)}
10207
 
10208
@item @emph{Arguments}:
10209
@multitable @columnfractions .15 .70
10210
@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10211
or @code{COMPLEX}.
10212
@end multitable
10213
 
10214
@item @emph{Return value}:
10215
The return value is of type @code{INTEGER} and of the default integer
10216
kind.
10217
 
10218
@item @emph{See also}:
10219
@ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10220
 
10221
@item @emph{Example}:
10222
See @code{PRECISION} for an example.
10223
@end table
10224
 
10225
 
10226
 
10227
@node RANK
10228
@section @code{RANK} --- Rank of a data object
10229
@fnindex RANK
10230
@cindex rank
10231
 
10232
@table @asis
10233
@item @emph{Description}:
10234
@code{RANK(A)} returns the rank of a scalar or array data object.
10235
 
10236
@item @emph{Standard}:
10237
Technical Specification (TS) 29113
10238
 
10239
@item @emph{Class}:
10240
Inquiry function
10241
 
10242
@item @emph{Syntax}:
10243
@code{RESULT = RANGE(A)}
10244
 
10245
@item @emph{Arguments}:
10246
@multitable @columnfractions .15 .70
10247
@item @var{A} @tab can be of any type
10248
@end multitable
10249
 
10250
@item @emph{Return value}:
10251
The return value is of type @code{INTEGER} and of the default integer
10252
kind. For arrays, their rank is returned; for scalars zero is returned.
10253
 
10254
@item @emph{Example}:
10255
@smallexample
10256
program test_rank
10257
  integer :: a
10258
  real, allocatable :: b(:,:)
10259
 
10260
  print *, rank(a), rank(b) ! Prints:  0  3
10261
end program test_rank
10262
@end smallexample
10263
 
10264
@end table
10265
 
10266
 
10267
 
10268
@node REAL
10269
@section @code{REAL} --- Convert to real type
10270
@fnindex REAL
10271
@fnindex REALPART
10272
@fnindex FLOAT
10273
@fnindex DFLOAT
10274
@fnindex SNGL
10275
@cindex conversion, to real
10276
@cindex complex numbers, real part
10277
 
10278
@table @asis
10279
@item @emph{Description}:
10280
@code{REAL(A [, KIND])} converts its argument @var{A} to a real type.  The
10281
@code{REALPART} function is provided for compatibility with @command{g77},
10282
and its use is strongly discouraged.
10283
 
10284
@item @emph{Standard}:
10285
Fortran 77 and later
10286
 
10287
@item @emph{Class}:
10288
Elemental function
10289
 
10290
@item @emph{Syntax}:
10291
@multitable @columnfractions .80
10292
@item @code{RESULT = REAL(A [, KIND])}
10293
@item @code{RESULT = REALPART(Z)}
10294
@end multitable
10295
 
10296
@item @emph{Arguments}:
10297
@multitable @columnfractions .15 .70
10298
@item @var{A}    @tab Shall be @code{INTEGER}, @code{REAL}, or
10299
@code{COMPLEX}.
10300
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10301
expression indicating the kind parameter of the result.
10302
@end multitable
10303
 
10304
@item @emph{Return value}:
10305
These functions return a @code{REAL} variable or array under
10306
the following rules:
10307
 
10308
@table @asis
10309
@item (A)
10310
@code{REAL(A)} is converted to a default real type if @var{A} is an
10311
integer or real variable.
10312
@item (B)
10313
@code{REAL(A)} is converted to a real type with the kind type parameter
10314
of @var{A} if @var{A} is a complex variable.
10315
@item (C)
10316
@code{REAL(A, KIND)} is converted to a real type with kind type
10317
parameter @var{KIND} if @var{A} is a complex, integer, or real
10318
variable.
10319
@end table
10320
 
10321
@item @emph{Example}:
10322
@smallexample
10323
program test_real
10324
  complex :: x = (1.0, 2.0)
10325
  print *, real(x), real(x,8), realpart(x)
10326
end program test_real
10327
@end smallexample
10328
 
10329
@item @emph{Specific names}:
10330
@multitable @columnfractions .20 .20 .20 .25
10331
@item Name             @tab Argument           @tab Return type     @tab Standard
10332
@item @code{FLOAT(A)}  @tab @code{INTEGER(4)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10333
@item @code{DFLOAT(A)} @tab @code{INTEGER(4)}  @tab @code{REAL(8)}  @tab GNU extension
10334
@item @code{SNGL(A)}   @tab @code{INTEGER(8)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10335
@end multitable
10336
 
10337
 
10338
@item @emph{See also}:
10339
@ref{DBLE}
10340
 
10341
@end table
10342
 
10343
 
10344
 
10345
@node RENAME
10346
@section @code{RENAME} --- Rename a file
10347
@fnindex RENAME
10348
@cindex file system, rename file
10349
 
10350
@table @asis
10351
@item @emph{Description}:
10352
Renames a file from file @var{PATH1} to @var{PATH2}. A null
10353
character (@code{CHAR(0)}) can be used to mark the end of the names in
10354
@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10355
names are ignored.  If the @var{STATUS} argument is supplied, it
10356
contains 0 on success or a nonzero error code upon return; see
10357
@code{rename(2)}.
10358
 
10359
This intrinsic is provided in both subroutine and function forms;
10360
however, only one form can be used in any given program unit.
10361
 
10362
@item @emph{Standard}:
10363
GNU extension
10364
 
10365
@item @emph{Class}:
10366
Subroutine, function
10367
 
10368
@item @emph{Syntax}:
10369
@multitable @columnfractions .80
10370
@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10371
@item @code{STATUS = RENAME(PATH1, PATH2)}
10372
@end multitable
10373
 
10374
@item @emph{Arguments}:
10375
@multitable @columnfractions .15 .70
10376
@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10377
@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10378
@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10379
@end multitable
10380
 
10381
@item @emph{See also}:
10382
@ref{LINK}
10383
 
10384
@end table
10385
 
10386
 
10387
 
10388
@node REPEAT
10389
@section @code{REPEAT} --- Repeated string concatenation
10390
@fnindex REPEAT
10391
@cindex string, repeat
10392
@cindex string, concatenate
10393
 
10394
@table @asis
10395
@item @emph{Description}:
10396
Concatenates @var{NCOPIES} copies of a string.
10397
 
10398
@item @emph{Standard}:
10399
Fortran 95 and later
10400
 
10401
@item @emph{Class}:
10402
Transformational function
10403
 
10404
@item @emph{Syntax}:
10405
@code{RESULT = REPEAT(STRING, NCOPIES)}
10406
 
10407
@item @emph{Arguments}:
10408
@multitable @columnfractions .15 .70
10409
@item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER}.
10410
@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10411
@end multitable
10412
 
10413
@item @emph{Return value}:
10414
A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10415
of @var{STRING}.
10416
 
10417
@item @emph{Example}:
10418
@smallexample
10419
program test_repeat
10420
  write(*,*) repeat("x", 5)   ! "xxxxx"
10421
end program
10422
@end smallexample
10423
@end table
10424
 
10425
 
10426
 
10427
@node RESHAPE
10428
@section @code{RESHAPE} --- Function to reshape an array
10429
@fnindex RESHAPE
10430
@cindex array, change dimensions
10431
@cindex array, transmogrify
10432
 
10433
@table @asis
10434
@item @emph{Description}:
10435
Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10436
the new array may be padded with elements from @var{PAD} or permuted
10437
as defined by @var{ORDER}.
10438
 
10439
@item @emph{Standard}:
10440
Fortran 95 and later
10441
 
10442
@item @emph{Class}:
10443
Transformational function
10444
 
10445
@item @emph{Syntax}:
10446
@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10447
 
10448
@item @emph{Arguments}:
10449
@multitable @columnfractions .15 .70
10450
@item @var{SOURCE} @tab Shall be an array of any type.
10451
@item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an
10452
array of rank one. Its values must be positive or zero.
10453
@item @var{PAD}    @tab (Optional) shall be an array of the same
10454
type as @var{SOURCE}.
10455
@item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
10456
and an array of the same shape as @var{SHAPE}. Its values shall
10457
be a permutation of the numbers from 1 to n, where n is the size of
10458
@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10459
be assumed.
10460
@end multitable
10461
 
10462
@item @emph{Return value}:
10463
The result is an array of shape @var{SHAPE} with the same type as
10464
@var{SOURCE}.
10465
 
10466
@item @emph{Example}:
10467
@smallexample
10468
PROGRAM test_reshape
10469
  INTEGER, DIMENSION(4) :: x
10470
  WRITE(*,*) SHAPE(x)                       ! prints "4"
10471
  WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
10472
END PROGRAM
10473
@end smallexample
10474
 
10475
@item @emph{See also}:
10476
@ref{SHAPE}
10477
@end table
10478
 
10479
 
10480
 
10481
@node RRSPACING
10482
@section @code{RRSPACING} --- Reciprocal of the relative spacing
10483
@fnindex RRSPACING
10484
@cindex real number, relative spacing
10485
@cindex floating point, relative spacing
10486
 
10487
 
10488
@table @asis
10489
@item @emph{Description}:
10490
@code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
10491
model numbers near @var{X}.
10492
 
10493
@item @emph{Standard}:
10494
Fortran 95 and later
10495
 
10496
@item @emph{Class}:
10497
Elemental function
10498
 
10499
@item @emph{Syntax}:
10500
@code{RESULT = RRSPACING(X)}
10501
 
10502
@item @emph{Arguments}:
10503
@multitable @columnfractions .15 .70
10504
@item @var{X} @tab Shall be of type @code{REAL}.
10505
@end multitable
10506
 
10507
@item @emph{Return value}:
10508
The return value is of the same type and kind as @var{X}.
10509
The value returned is equal to
10510
@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10511
 
10512
@item @emph{See also}:
10513
@ref{SPACING}
10514
@end table
10515
 
10516
 
10517
 
10518
@node RSHIFT
10519
@section @code{RSHIFT} --- Right shift bits
10520
@fnindex RSHIFT
10521
@cindex bits, shift right
10522
 
10523
@table @asis
10524
@item @emph{Description}:
10525
@code{RSHIFT} returns a value corresponding to @var{I} with all of the
10526
bits shifted right by @var{SHIFT} places.  If the absolute value of
10527
@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10528
Bits shifted out from the right end are lost. The fill is arithmetic: the
10529
bits shifted in from the left end are equal to the leftmost bit, which in
10530
two's complement representation is the sign bit.
10531
 
10532
This function has been superseded by the @code{SHIFTA} intrinsic, which
10533
is standard in Fortran 2008 and later.
10534
 
10535
@item @emph{Standard}:
10536
GNU extension
10537
 
10538
@item @emph{Class}:
10539
Elemental function
10540
 
10541
@item @emph{Syntax}:
10542
@code{RESULT = RSHIFT(I, SHIFT)}
10543
 
10544
@item @emph{Arguments}:
10545
@multitable @columnfractions .15 .70
10546
@item @var{I} @tab The type shall be @code{INTEGER}.
10547
@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10548
@end multitable
10549
 
10550
@item @emph{Return value}:
10551
The return value is of type @code{INTEGER} and of the same kind as
10552
@var{I}.
10553
 
10554
@item @emph{See also}:
10555
@ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10556
@ref{SHIFTL}
10557
 
10558
@end table
10559
 
10560
 
10561
 
10562
@node SAME_TYPE_AS
10563
@section @code{SAME_TYPE_AS} ---  Query dynamic types for equality
10564
@fnindex SAME_TYPE_AS
10565
 
10566
@table @asis
10567
@item @emph{Description}:
10568
Query dynamic types for equality.
10569
 
10570
@item @emph{Standard}:
10571
Fortran 2003 and later
10572
 
10573
@item @emph{Class}:
10574
Inquiry function
10575
 
10576
@item @emph{Syntax}:
10577
@code{RESULT = SAME_TYPE_AS(A, B)}
10578
 
10579
@item @emph{Arguments}:
10580
@multitable @columnfractions .15 .70
10581
@item @var{A} @tab Shall be an object of extensible declared type or
10582
unlimited polymorphic.
10583
@item @var{B} @tab Shall be an object of extensible declared type or
10584
unlimited polymorphic.
10585
@end multitable
10586
 
10587
@item @emph{Return value}:
10588
The return value is a scalar of type default logical. It is true if and
10589
only if the dynamic type of A is the same as the dynamic type of B.
10590
 
10591
@item @emph{See also}:
10592
@ref{EXTENDS_TYPE_OF}
10593
 
10594
@end table
10595
 
10596
 
10597
 
10598
@node SCALE
10599
@section @code{SCALE} --- Scale a real value
10600
@fnindex SCALE
10601
@cindex real number, scale
10602
@cindex floating point, scale
10603
 
10604
@table @asis
10605
@item @emph{Description}:
10606
@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10607
 
10608
@item @emph{Standard}:
10609
Fortran 95 and later
10610
 
10611
@item @emph{Class}:
10612
Elemental function
10613
 
10614
@item @emph{Syntax}:
10615
@code{RESULT = SCALE(X, I)}
10616
 
10617
@item @emph{Arguments}:
10618
@multitable @columnfractions .15 .70
10619
@item @var{X} @tab The type of the argument shall be a @code{REAL}.
10620
@item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10621
@end multitable
10622
 
10623
@item @emph{Return value}:
10624
The return value is of the same type and kind as @var{X}.
10625
Its value is @code{X * RADIX(X)**I}.
10626
 
10627
@item @emph{Example}:
10628
@smallexample
10629
program test_scale
10630
  real :: x = 178.1387e-4
10631
  integer :: i = 5
10632
  print *, scale(x,i), x*radix(x)**i
10633
end program test_scale
10634
@end smallexample
10635
 
10636
@end table
10637
 
10638
 
10639
 
10640
@node SCAN
10641
@section @code{SCAN} --- Scan a string for the presence of a set of characters
10642
@fnindex SCAN
10643
@cindex string, find subset
10644
 
10645
@table @asis
10646
@item @emph{Description}:
10647
Scans a @var{STRING} for any of the characters in a @var{SET}
10648
of characters.
10649
 
10650
If @var{BACK} is either absent or equals @code{FALSE}, this function
10651
returns the position of the leftmost character of @var{STRING} that is
10652
in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10653
is returned. If no character of @var{SET} is found in @var{STRING}, the
10654
result is zero.
10655
 
10656
@item @emph{Standard}:
10657
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10658
 
10659
@item @emph{Class}:
10660
Elemental function
10661
 
10662
@item @emph{Syntax}:
10663
@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10664
 
10665
@item @emph{Arguments}:
10666
@multitable @columnfractions .15 .70
10667
@item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10668
@item @var{SET}    @tab Shall be of type @code{CHARACTER}.
10669
@item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
10670
@item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
10671
expression indicating the kind parameter of the result.
10672
@end multitable
10673
 
10674
@item @emph{Return value}:
10675
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10676
@var{KIND} is absent, the return value is of default integer kind.
10677
 
10678
@item @emph{Example}:
10679
@smallexample
10680
PROGRAM test_scan
10681
  WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
10682
  WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
10683
  WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
10684
END PROGRAM
10685
@end smallexample
10686
 
10687
@item @emph{See also}:
10688
@ref{INDEX intrinsic}, @ref{VERIFY}
10689
@end table
10690
 
10691
 
10692
 
10693
@node SECNDS
10694
@section @code{SECNDS} --- Time function
10695
@fnindex SECNDS
10696
@cindex time, elapsed
10697
@cindex elapsed time
10698
 
10699
@table @asis
10700
@item @emph{Description}:
10701
@code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10702
@var{X} is a reference time, also in seconds. If this is zero, the time in
10703
seconds from midnight is returned. This function is non-standard and its
10704
use is discouraged.
10705
 
10706
@item @emph{Standard}:
10707
GNU extension
10708
 
10709
@item @emph{Class}:
10710
Function
10711
 
10712
@item @emph{Syntax}:
10713
@code{RESULT = SECNDS (X)}
10714
 
10715
@item @emph{Arguments}:
10716
@multitable @columnfractions .15 .70
10717
@item @var{T}     @tab Shall be of type @code{REAL(4)}.
10718
@item @var{X}     @tab Shall be of type @code{REAL(4)}.
10719
@end multitable
10720
 
10721
@item @emph{Return value}:
10722
None
10723
 
10724
@item @emph{Example}:
10725
@smallexample
10726
program test_secnds
10727
    integer :: i
10728
    real(4) :: t1, t2
10729
    print *, secnds (0.0)   ! seconds since midnight
10730
    t1 = secnds (0.0)       ! reference time
10731
    do i = 1, 10000000      ! do something
10732
    end do
10733
    t2 = secnds (t1)        ! elapsed time
10734
    print *, "Something took ", t2, " seconds."
10735
end program test_secnds
10736
@end smallexample
10737
@end table
10738
 
10739
 
10740
 
10741
@node SECOND
10742
@section @code{SECOND} --- CPU time function
10743
@fnindex SECOND
10744
@cindex time, elapsed
10745
@cindex elapsed time
10746
 
10747
@table @asis
10748
@item @emph{Description}:
10749
Returns a @code{REAL(4)} value representing the elapsed CPU time in
10750
seconds.  This provides the same functionality as the standard
10751
@code{CPU_TIME} intrinsic, and is only included for backwards
10752
compatibility.
10753
 
10754
This intrinsic is provided in both subroutine and function forms;
10755
however, only one form can be used in any given program unit.
10756
 
10757
@item @emph{Standard}:
10758
GNU extension
10759
 
10760
@item @emph{Class}:
10761
Subroutine, function
10762
 
10763
@item @emph{Syntax}:
10764
@multitable @columnfractions .80
10765
@item @code{CALL SECOND(TIME)}
10766
@item @code{TIME = SECOND()}
10767
@end multitable
10768
 
10769
@item @emph{Arguments}:
10770
@multitable @columnfractions .15 .70
10771
@item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
10772
@end multitable
10773
 
10774
@item @emph{Return value}:
10775
In either syntax, @var{TIME} is set to the process's current runtime in
10776
seconds.
10777
 
10778
@item @emph{See also}:
10779
@ref{CPU_TIME}
10780
 
10781
@end table
10782
 
10783
 
10784
 
10785
@node SELECTED_CHAR_KIND
10786
@section @code{SELECTED_CHAR_KIND} --- Choose character kind
10787
@fnindex SELECTED_CHAR_KIND
10788
@cindex character kind
10789
@cindex kind, character
10790
 
10791
@table @asis
10792
@item @emph{Description}:
10793
 
10794
@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10795
set named @var{NAME}, if a character set with such a name is supported,
10796
or @math{-1} otherwise. Currently, supported character sets include
10797
``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10798
(Universal Character Set, UCS-4) which is commonly known as Unicode.
10799
 
10800
@item @emph{Standard}:
10801
Fortran 2003 and later
10802
 
10803
@item @emph{Class}:
10804
Transformational function
10805
 
10806
@item @emph{Syntax}:
10807
@code{RESULT = SELECTED_CHAR_KIND(NAME)}
10808
 
10809
@item @emph{Arguments}:
10810
@multitable @columnfractions .15 .70
10811
@item @var{NAME} @tab Shall be a scalar and of the default character type.
10812
@end multitable
10813
 
10814
@item @emph{Example}:
10815
@smallexample
10816
program character_kind
10817
  use iso_fortran_env
10818
  implicit none
10819
  integer, parameter :: ascii = selected_char_kind ("ascii")
10820
  integer, parameter :: ucs4  = selected_char_kind ('ISO_10646')
10821
 
10822
  character(kind=ascii, len=26) :: alphabet
10823
  character(kind=ucs4,  len=30) :: hello_world
10824
 
10825
  alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10826
  hello_world = ucs4_'Hello World and Ni Hao -- ' &
10827
                // char (int (z'4F60'), ucs4)     &
10828
                // char (int (z'597D'), ucs4)
10829
 
10830
  write (*,*) alphabet
10831
 
10832
  open (output_unit, encoding='UTF-8')
10833
  write (*,*) trim (hello_world)
10834
end program character_kind
10835
@end smallexample
10836
@end table
10837
 
10838
 
10839
 
10840
@node SELECTED_INT_KIND
10841
@section @code{SELECTED_INT_KIND} --- Choose integer kind
10842
@fnindex SELECTED_INT_KIND
10843
@cindex integer kind
10844
@cindex kind, integer
10845
 
10846
@table @asis
10847
@item @emph{Description}:
10848
@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10849
type that can represent all values ranging from @math{-10^R} (exclusive)
10850
to @math{10^R} (exclusive). If there is no integer kind that accommodates
10851
this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10852
 
10853
@item @emph{Standard}:
10854
Fortran 95 and later
10855
 
10856
@item @emph{Class}:
10857
Transformational function
10858
 
10859
@item @emph{Syntax}:
10860
@code{RESULT = SELECTED_INT_KIND(R)}
10861
 
10862
@item @emph{Arguments}:
10863
@multitable @columnfractions .15 .70
10864
@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10865
@end multitable
10866
 
10867
@item @emph{Example}:
10868
@smallexample
10869
program large_integers
10870
  integer,parameter :: k5 = selected_int_kind(5)
10871
  integer,parameter :: k15 = selected_int_kind(15)
10872
  integer(kind=k5) :: i5
10873
  integer(kind=k15) :: i15
10874
 
10875
  print *, huge(i5), huge(i15)
10876
 
10877
  ! The following inequalities are always true
10878
  print *, huge(i5) >= 10_k5**5-1
10879
  print *, huge(i15) >= 10_k15**15-1
10880
end program large_integers
10881
@end smallexample
10882
@end table
10883
 
10884
 
10885
 
10886
@node SELECTED_REAL_KIND
10887
@section @code{SELECTED_REAL_KIND} --- Choose real kind
10888
@fnindex SELECTED_REAL_KIND
10889
@cindex real kind
10890
@cindex kind, real
10891
@cindex radix, real
10892
 
10893
@table @asis
10894
@item @emph{Description}:
10895
@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10896
with decimal precision of at least @code{P} digits, exponent range of
10897
at least @code{R}, and with a radix of @code{RADIX}.
10898
 
10899
@item @emph{Standard}:
10900
Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10901
 
10902
@item @emph{Class}:
10903
Transformational function
10904
 
10905
@item @emph{Syntax}:
10906
@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10907
 
10908
@item @emph{Arguments}:
10909
@multitable @columnfractions .15 .70
10910
@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10911
@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10912
@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10913
@end multitable
10914
Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10915
be present; since Fortran 2008, they are assumed to be zero if absent.
10916
 
10917
@item @emph{Return value}:
10918
 
10919
@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10920
a real data type with decimal precision of at least @code{P} digits, a
10921
decimal exponent range of at least @code{R}, and with the requested
10922
@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10923
any radix can be returned. If more than one real data type meet the
10924
criteria, the kind of the data type with the smallest decimal precision
10925
is returned. If no real data type matches the criteria, the result is
10926
@table @asis
10927
@item -1 if the processor does not support a real data type with a
10928
precision greater than or equal to @code{P}, but the @code{R} and
10929
@code{RADIX} requirements can be fulfilled
10930
@item -2 if the processor does not support a real type with an exponent
10931
range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10932
are fulfillable
10933
@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10934
are fulfillable
10935
@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10936
are fulfillable
10937
@item -5 if there is no real type with the given @code{RADIX}
10938
@end table
10939
 
10940
@item @emph{See also}:
10941
@ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10942
 
10943
@item @emph{Example}:
10944
@smallexample
10945
program real_kinds
10946
  integer,parameter :: p6 = selected_real_kind(6)
10947
  integer,parameter :: p10r100 = selected_real_kind(10,100)
10948
  integer,parameter :: r400 = selected_real_kind(r=400)
10949
  real(kind=p6) :: x
10950
  real(kind=p10r100) :: y
10951
  real(kind=r400) :: z
10952
 
10953
  print *, precision(x), range(x)
10954
  print *, precision(y), range(y)
10955
  print *, precision(z), range(z)
10956
end program real_kinds
10957
@end smallexample
10958
@end table
10959
 
10960
 
10961
 
10962
@node SET_EXPONENT
10963
@section @code{SET_EXPONENT} --- Set the exponent of the model
10964
@fnindex SET_EXPONENT
10965
@cindex real number, set exponent
10966
@cindex floating point, set exponent
10967
 
10968
@table @asis
10969
@item @emph{Description}:
10970
@code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10971
is that that of @var{X} and whose exponent part is @var{I}.
10972
 
10973
@item @emph{Standard}:
10974
Fortran 95 and later
10975
 
10976
@item @emph{Class}:
10977
Elemental function
10978
 
10979
@item @emph{Syntax}:
10980
@code{RESULT = SET_EXPONENT(X, I)}
10981
 
10982
@item @emph{Arguments}:
10983
@multitable @columnfractions .15 .70
10984
@item @var{X} @tab Shall be of type @code{REAL}.
10985
@item @var{I} @tab Shall be of type @code{INTEGER}.
10986
@end multitable
10987
 
10988
@item @emph{Return value}:
10989
The return value is of the same type and kind as @var{X}.
10990
The real number whose fractional part
10991
is that that of @var{X} and whose exponent part if @var{I} is returned;
10992
it is @code{FRACTION(X) * RADIX(X)**I}.
10993
 
10994
@item @emph{Example}:
10995
@smallexample
10996
PROGRAM test_setexp
10997
  REAL :: x = 178.1387e-4
10998
  INTEGER :: i = 17
10999
  PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
11000
END PROGRAM
11001
@end smallexample
11002
 
11003
@end table
11004
 
11005
 
11006
 
11007
@node SHAPE
11008
@section @code{SHAPE} --- Determine the shape of an array
11009
@fnindex SHAPE
11010
@cindex array, shape
11011
 
11012
@table @asis
11013
@item @emph{Description}:
11014
Determines the shape of an array.
11015
 
11016
@item @emph{Standard}:
11017
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11018
 
11019
@item @emph{Class}:
11020
Inquiry function
11021
 
11022
@item @emph{Syntax}:
11023
@code{RESULT = SHAPE(SOURCE [, KIND])}
11024
 
11025
@item @emph{Arguments}:
11026
@multitable @columnfractions .15 .70
11027
@item @var{SOURCE} @tab Shall be an array or scalar of any type.
11028
If @var{SOURCE} is a pointer it must be associated and allocatable
11029
arrays must be allocated.
11030
@item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
11031
expression indicating the kind parameter of the result.
11032
@end multitable
11033
 
11034
@item @emph{Return value}:
11035
An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11036
has dimensions. The elements of the resulting array correspond to the extend
11037
of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11038
the result is the rank one array of size zero. If @var{KIND} is absent, the
11039
return value has the default integer kind otherwise the specified kind.
11040
 
11041
@item @emph{Example}:
11042
@smallexample
11043
PROGRAM test_shape
11044
  INTEGER, DIMENSION(-1:1, -1:2) :: A
11045
  WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
11046
  WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
11047
END PROGRAM
11048
@end smallexample
11049
 
11050
@item @emph{See also}:
11051
@ref{RESHAPE}, @ref{SIZE}
11052
@end table
11053
 
11054
 
11055
 
11056
@node SHIFTA
11057
@section @code{SHIFTA} --- Right shift with fill
11058
@fnindex SHIFTA
11059
@cindex bits, shift right
11060
@cindex shift, right with fill
11061
 
11062
@table @asis
11063
@item @emph{Description}:
11064
@code{SHIFTA} returns a value corresponding to @var{I} with all of the
11065
bits shifted right by @var{SHIFT} places.  If the absolute value of
11066
@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11067
Bits shifted out from the right end are lost. The fill is arithmetic: the
11068
bits shifted in from the left end are equal to the leftmost bit, which in
11069
two's complement representation is the sign bit.
11070
 
11071
@item @emph{Standard}:
11072
Fortran 2008 and later
11073
 
11074
@item @emph{Class}:
11075
Elemental function
11076
 
11077
@item @emph{Syntax}:
11078
@code{RESULT = SHIFTA(I, SHIFT)}
11079
 
11080
@item @emph{Arguments}:
11081
@multitable @columnfractions .15 .70
11082
@item @var{I} @tab The type shall be @code{INTEGER}.
11083
@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11084
@end multitable
11085
 
11086
@item @emph{Return value}:
11087
The return value is of type @code{INTEGER} and of the same kind as
11088
@var{I}.
11089
 
11090
@item @emph{See also}:
11091
@ref{SHIFTL}, @ref{SHIFTR}
11092
@end table
11093
 
11094
 
11095
 
11096
@node SHIFTL
11097
@section @code{SHIFTL} --- Left shift
11098
@fnindex SHIFTL
11099
@cindex bits, shift left
11100
@cindex shift, left
11101
 
11102
@table @asis
11103
@item @emph{Description}:
11104
@code{SHIFTL} returns a value corresponding to @var{I} with all of the
11105
bits shifted left by @var{SHIFT} places.  If the absolute value of
11106
@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11107
Bits shifted out from the left end are lost, and bits shifted in from
11108
the right end are set to 0.
11109
 
11110
@item @emph{Standard}:
11111
Fortran 2008 and later
11112
 
11113
@item @emph{Class}:
11114
Elemental function
11115
 
11116
@item @emph{Syntax}:
11117
@code{RESULT = SHIFTL(I, SHIFT)}
11118
 
11119
@item @emph{Arguments}:
11120
@multitable @columnfractions .15 .70
11121
@item @var{I} @tab The type shall be @code{INTEGER}.
11122
@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11123
@end multitable
11124
 
11125
@item @emph{Return value}:
11126
The return value is of type @code{INTEGER} and of the same kind as
11127
@var{I}.
11128
 
11129
@item @emph{See also}:
11130
@ref{SHIFTA}, @ref{SHIFTR}
11131
@end table
11132
 
11133
 
11134
 
11135
@node SHIFTR
11136
@section @code{SHIFTR} --- Right shift
11137
@fnindex SHIFTR
11138
@cindex bits, shift right
11139
@cindex shift, right
11140
 
11141
@table @asis
11142
@item @emph{Description}:
11143
@code{SHIFTR} returns a value corresponding to @var{I} with all of the
11144
bits shifted right by @var{SHIFT} places.  If the absolute value of
11145
@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11146
Bits shifted out from the right end are lost, and bits shifted in from
11147
the left end are set to 0.
11148
 
11149
@item @emph{Standard}:
11150
Fortran 2008 and later
11151
 
11152
@item @emph{Class}:
11153
Elemental function
11154
 
11155
@item @emph{Syntax}:
11156
@code{RESULT = SHIFTR(I, SHIFT)}
11157
 
11158
@item @emph{Arguments}:
11159
@multitable @columnfractions .15 .70
11160
@item @var{I} @tab The type shall be @code{INTEGER}.
11161
@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11162
@end multitable
11163
 
11164
@item @emph{Return value}:
11165
The return value is of type @code{INTEGER} and of the same kind as
11166
@var{I}.
11167
 
11168
@item @emph{See also}:
11169
@ref{SHIFTA}, @ref{SHIFTL}
11170
@end table
11171
 
11172
 
11173
 
11174
@node SIGN
11175
@section @code{SIGN} --- Sign copying function
11176
@fnindex SIGN
11177
@fnindex ISIGN
11178
@fnindex DSIGN
11179
@cindex sign copying
11180
 
11181
@table @asis
11182
@item @emph{Description}:
11183
@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11184
 
11185
@item @emph{Standard}:
11186
Fortran 77 and later
11187
 
11188
@item @emph{Class}:
11189
Elemental function
11190
 
11191
@item @emph{Syntax}:
11192
@code{RESULT = SIGN(A, B)}
11193
 
11194
@item @emph{Arguments}:
11195
@multitable @columnfractions .15 .70
11196
@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11197
@item @var{B} @tab Shall be of the same type and kind as @var{A}
11198
@end multitable
11199
 
11200
@item @emph{Return value}:
11201
The kind of the return value is that of @var{A} and @var{B}.
11202
If @math{B\ge 0} then the result is @code{ABS(A)}, else
11203
it is @code{-ABS(A)}.
11204
 
11205
@item @emph{Example}:
11206
@smallexample
11207
program test_sign
11208
  print *, sign(-12,1)
11209
  print *, sign(-12,0)
11210
  print *, sign(-12,-1)
11211
 
11212
  print *, sign(-12.,1.)
11213
  print *, sign(-12.,0.)
11214
  print *, sign(-12.,-1.)
11215
end program test_sign
11216
@end smallexample
11217
 
11218
@item @emph{Specific names}:
11219
@multitable @columnfractions .20 .20 .20 .25
11220
@item Name              @tab Arguments              @tab Return type       @tab Standard
11221
@item @code{SIGN(A,B)}  @tab @code{REAL(4) A, B}    @tab @code{REAL(4)}    @tab f77, gnu
11222
@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11223
@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B}    @tab @code{REAL(8)}    @tab f77, gnu
11224
@end multitable
11225
@end table
11226
 
11227
 
11228
 
11229
@node SIGNAL
11230
@section @code{SIGNAL} --- Signal handling subroutine (or function)
11231
@fnindex SIGNAL
11232
@cindex system, signal handling
11233
 
11234
@table @asis
11235
@item @emph{Description}:
11236
@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11237
@var{HANDLER} to be executed with a single integer argument when signal
11238
@var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
11239
turn off handling of signal @var{NUMBER} or revert to its default
11240
action.  See @code{signal(2)}.
11241
 
11242
If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11243
is supplied, it is set to the value returned by @code{signal(2)}.
11244
 
11245
@item @emph{Standard}:
11246
GNU extension
11247
 
11248
@item @emph{Class}:
11249
Subroutine, function
11250
 
11251
@item @emph{Syntax}:
11252
@multitable @columnfractions .80
11253
@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11254
@item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11255
@end multitable
11256
 
11257
@item @emph{Arguments}:
11258
@multitable @columnfractions .15 .70
11259
@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11260
@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11261
@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11262
@code{INTEGER}. It is @code{INTENT(IN)}.
11263
@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11264
integer. It has @code{INTENT(OUT)}.
11265
@end multitable
11266
@c TODO: What should the interface of the handler be?  Does it take arguments?
11267
 
11268
@item @emph{Return value}:
11269
The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11270
 
11271
@item @emph{Example}:
11272
@smallexample
11273
program test_signal
11274
  intrinsic signal
11275
  external handler_print
11276
 
11277
  call signal (12, handler_print)
11278
  call signal (10, 1)
11279
 
11280
  call sleep (30)
11281
end program test_signal
11282
@end smallexample
11283
@end table
11284
 
11285
 
11286
 
11287
@node SIN
11288
@section @code{SIN} --- Sine function
11289
@fnindex SIN
11290
@fnindex DSIN
11291
@fnindex CSIN
11292
@fnindex ZSIN
11293
@fnindex CDSIN
11294
@cindex trigonometric function, sine
11295
@cindex sine
11296
 
11297
@table @asis
11298
@item @emph{Description}:
11299
@code{SIN(X)} computes the sine of @var{X}.
11300
 
11301
@item @emph{Standard}:
11302
Fortran 77 and later
11303
 
11304
@item @emph{Class}:
11305
Elemental function
11306
 
11307
@item @emph{Syntax}:
11308
@code{RESULT = SIN(X)}
11309
 
11310
@item @emph{Arguments}:
11311
@multitable @columnfractions .15 .70
11312
@item @var{X} @tab The type shall be @code{REAL} or
11313
@code{COMPLEX}.
11314
@end multitable
11315
 
11316
@item @emph{Return value}:
11317
The return value has same type and kind as @var{X}.
11318
 
11319
@item @emph{Example}:
11320
@smallexample
11321
program test_sin
11322
  real :: x = 0.0
11323
  x = sin(x)
11324
end program test_sin
11325
@end smallexample
11326
 
11327
@item @emph{Specific names}:
11328
@multitable @columnfractions .20 .20 .20 .25
11329
@item Name            @tab Argument             @tab Return type       @tab Standard
11330
@item @code{SIN(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}    @tab f77, gnu
11331
@item @code{DSIN(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}    @tab f95, gnu
11332
@item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)} @tab f95, gnu
11333
@item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11334
@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11335
@end multitable
11336
 
11337
@item @emph{See also}:
11338
@ref{ASIN}
11339
@end table
11340
 
11341
 
11342
 
11343
@node SINH
11344
@section @code{SINH} --- Hyperbolic sine function
11345
@fnindex SINH
11346
@fnindex DSINH
11347
@cindex hyperbolic sine
11348
@cindex hyperbolic function, sine
11349
@cindex sine, hyperbolic
11350
 
11351
@table @asis
11352
@item @emph{Description}:
11353
@code{SINH(X)} computes the hyperbolic sine of @var{X}.
11354
 
11355
@item @emph{Standard}:
11356
Fortran 95 and later, for a complex argument Fortran 2008 or later
11357
 
11358
@item @emph{Class}:
11359
Elemental function
11360
 
11361
@item @emph{Syntax}:
11362
@code{RESULT = SINH(X)}
11363
 
11364
@item @emph{Arguments}:
11365
@multitable @columnfractions .15 .70
11366
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11367
@end multitable
11368
 
11369
@item @emph{Return value}:
11370
The return value has same type and kind as @var{X}.
11371
 
11372
@item @emph{Example}:
11373
@smallexample
11374
program test_sinh
11375
  real(8) :: x = - 1.0_8
11376
  x = sinh(x)
11377
end program test_sinh
11378
@end smallexample
11379
 
11380
@item @emph{Specific names}:
11381
@multitable @columnfractions .20 .20 .20 .25
11382
@item Name            @tab Argument          @tab Return type       @tab Standard
11383
@item @code{SINH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
11384
@item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
11385
@end multitable
11386
 
11387
@item @emph{See also}:
11388
@ref{ASINH}
11389
@end table
11390
 
11391
 
11392
 
11393
@node SIZE
11394
@section @code{SIZE} --- Determine the size of an array
11395
@fnindex SIZE
11396
@cindex array, size
11397
@cindex array, number of elements
11398
@cindex array, count elements
11399
 
11400
@table @asis
11401
@item @emph{Description}:
11402
Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11403
or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11404
 
11405
@item @emph{Standard}:
11406
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11407
 
11408
@item @emph{Class}:
11409
Inquiry function
11410
 
11411
@item @emph{Syntax}:
11412
@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11413
 
11414
@item @emph{Arguments}:
11415
@multitable @columnfractions .15 .70
11416
@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11417
a pointer it must be associated and allocatable arrays must be allocated.
11418
@item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER}
11419
and its value shall be in the range from 1 to n, where n equals the rank
11420
of @var{ARRAY}.
11421
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11422
expression indicating the kind parameter of the result.
11423
@end multitable
11424
 
11425
@item @emph{Return value}:
11426
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11427
@var{KIND} is absent, the return value is of default integer kind.
11428
 
11429
@item @emph{Example}:
11430
@smallexample
11431
PROGRAM test_size
11432
  WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
11433
END PROGRAM
11434
@end smallexample
11435
 
11436
@item @emph{See also}:
11437
@ref{SHAPE}, @ref{RESHAPE}
11438
@end table
11439
 
11440
 
11441
@node SIZEOF
11442
@section @code{SIZEOF} --- Size in bytes of an expression
11443
@fnindex SIZEOF
11444
@cindex expression size
11445
@cindex size of an expression
11446
 
11447
@table @asis
11448
@item @emph{Description}:
11449
@code{SIZEOF(X)} calculates the number of bytes of storage the
11450
expression @code{X} occupies.
11451
 
11452
@item @emph{Standard}:
11453
GNU extension
11454
 
11455
@item @emph{Class}:
11456
Intrinsic function
11457
 
11458
@item @emph{Syntax}:
11459
@code{N = SIZEOF(X)}
11460
 
11461
@item @emph{Arguments}:
11462
@multitable @columnfractions .15 .70
11463
@item @var{X} @tab The argument shall be of any type, rank or shape.
11464
@end multitable
11465
 
11466
@item @emph{Return value}:
11467
The return value is of type integer and of the system-dependent kind
11468
@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11469
number of bytes occupied by the argument.  If the argument has the
11470
@code{POINTER} attribute, the number of bytes of the storage area pointed
11471
to is returned.  If the argument is of a derived type with @code{POINTER}
11472
or @code{ALLOCATABLE} components, the return value does not account for
11473
the sizes of the data pointed to by these components. If the argument is
11474
polymorphic, the size according to the declared type is returned. The argument
11475
may not be a procedure or procedure pointer.
11476
 
11477
@item @emph{Example}:
11478
@smallexample
11479
   integer :: i
11480
   real :: r, s(5)
11481
   print *, (sizeof(s)/sizeof(r) == 5)
11482
   end
11483
@end smallexample
11484
The example will print @code{.TRUE.} unless you are using a platform
11485
where default @code{REAL} variables are unusually padded.
11486
 
11487
@item @emph{See also}:
11488
@ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11489
@end table
11490
 
11491
 
11492
@node SLEEP
11493
@section @code{SLEEP} --- Sleep for the specified number of seconds
11494
@fnindex SLEEP
11495
@cindex delayed execution
11496
 
11497
@table @asis
11498
@item @emph{Description}:
11499
Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11500
 
11501
@item @emph{Standard}:
11502
GNU extension
11503
 
11504
@item @emph{Class}:
11505
Subroutine
11506
 
11507
@item @emph{Syntax}:
11508
@code{CALL SLEEP(SECONDS)}
11509
 
11510
@item @emph{Arguments}:
11511
@multitable @columnfractions .15 .70
11512
@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11513
@end multitable
11514
 
11515
@item @emph{Example}:
11516
@smallexample
11517
program test_sleep
11518
  call sleep(5)
11519
end
11520
@end smallexample
11521
@end table
11522
 
11523
 
11524
 
11525
@node SPACING
11526
@section @code{SPACING} --- Smallest distance between two numbers of a given type
11527
@fnindex SPACING
11528
@cindex real number, relative spacing
11529
@cindex floating point, relative spacing
11530
 
11531
@table @asis
11532
@item @emph{Description}:
11533
Determines the distance between the argument @var{X} and the nearest
11534
adjacent number of the same type.
11535
 
11536
@item @emph{Standard}:
11537
Fortran 95 and later
11538
 
11539
@item @emph{Class}:
11540
Elemental function
11541
 
11542
@item @emph{Syntax}:
11543
@code{RESULT = SPACING(X)}
11544
 
11545
@item @emph{Arguments}:
11546
@multitable @columnfractions .15 .70
11547
@item @var{X} @tab Shall be of type @code{REAL}.
11548
@end multitable
11549
 
11550
@item @emph{Return value}:
11551
The result is of the same type as the input argument @var{X}.
11552
 
11553
@item @emph{Example}:
11554
@smallexample
11555
PROGRAM test_spacing
11556
  INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11557
  INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11558
 
11559
  WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
11560
  WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
11561
END PROGRAM
11562
@end smallexample
11563
 
11564
@item @emph{See also}:
11565
@ref{RRSPACING}
11566
@end table
11567
 
11568
 
11569
 
11570
@node SPREAD
11571
@section @code{SPREAD} --- Add a dimension to an array
11572
@fnindex SPREAD
11573
@cindex array, increase dimension
11574
@cindex array, duplicate elements
11575
@cindex array, duplicate dimensions
11576
 
11577
@table @asis
11578
@item @emph{Description}:
11579
Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11580
dimension @var{DIM}.
11581
 
11582
@item @emph{Standard}:
11583
Fortran 95 and later
11584
 
11585
@item @emph{Class}:
11586
Transformational function
11587
 
11588
@item @emph{Syntax}:
11589
@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11590
 
11591
@item @emph{Arguments}:
11592
@multitable @columnfractions .15 .70
11593
@item @var{SOURCE}  @tab Shall be a scalar or an array of any type and
11594
a rank less than seven.
11595
@item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a
11596
value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11597
@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11598
@end multitable
11599
 
11600
@item @emph{Return value}:
11601
The result is an array of the same type as @var{SOURCE} and has rank n+1
11602
where n equals the rank of @var{SOURCE}.
11603
 
11604
@item @emph{Example}:
11605
@smallexample
11606
PROGRAM test_spread
11607
  INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11608
  WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
11609
  WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
11610
END PROGRAM
11611
@end smallexample
11612
 
11613
@item @emph{See also}:
11614
@ref{UNPACK}
11615
@end table
11616
 
11617
 
11618
 
11619
@node SQRT
11620
@section @code{SQRT} --- Square-root function
11621
@fnindex SQRT
11622
@fnindex DSQRT
11623
@fnindex CSQRT
11624
@fnindex ZSQRT
11625
@fnindex CDSQRT
11626
@cindex root
11627
@cindex square-root
11628
 
11629
@table @asis
11630
@item @emph{Description}:
11631
@code{SQRT(X)} computes the square root of @var{X}.
11632
 
11633
@item @emph{Standard}:
11634
Fortran 77 and later
11635
 
11636
@item @emph{Class}:
11637
Elemental function
11638
 
11639
@item @emph{Syntax}:
11640
@code{RESULT = SQRT(X)}
11641
 
11642
@item @emph{Arguments}:
11643
@multitable @columnfractions .15 .70
11644
@item @var{X} @tab The type shall be @code{REAL} or
11645
@code{COMPLEX}.
11646
@end multitable
11647
 
11648
@item @emph{Return value}:
11649
The return value is of type @code{REAL} or @code{COMPLEX}.
11650
The kind type parameter is the same as @var{X}.
11651
 
11652
@item @emph{Example}:
11653
@smallexample
11654
program test_sqrt
11655
  real(8) :: x = 2.0_8
11656
  complex :: z = (1.0, 2.0)
11657
  x = sqrt(x)
11658
  z = sqrt(z)
11659
end program test_sqrt
11660
@end smallexample
11661
 
11662
@item @emph{Specific names}:
11663
@multitable @columnfractions .20 .20 .20 .25
11664
@item Name             @tab Argument             @tab Return type          @tab Standard
11665
@item @code{SQRT(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}       @tab Fortran 95 and later
11666
@item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab Fortran 95 and later
11667
@item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 95 and later
11668
@item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11669
@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11670
@end multitable
11671
@end table
11672
 
11673
 
11674
 
11675
@node SRAND
11676
@section @code{SRAND} --- Reinitialize the random number generator
11677
@fnindex SRAND
11678
@cindex random number generation, seeding
11679
@cindex seeding a random number generator
11680
 
11681
@table @asis
11682
@item @emph{Description}:
11683
@code{SRAND} reinitializes the pseudo-random number generator
11684
called by @code{RAND} and @code{IRAND}. The new seed used by the
11685
generator is specified by the required argument @var{SEED}.
11686
 
11687
@item @emph{Standard}:
11688
GNU extension
11689
 
11690
@item @emph{Class}:
11691
Subroutine
11692
 
11693
@item @emph{Syntax}:
11694
@code{CALL SRAND(SEED)}
11695
 
11696
@item @emph{Arguments}:
11697
@multitable @columnfractions .15 .70
11698
@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11699
@end multitable
11700
 
11701
@item @emph{Return value}:
11702
Does not return anything.
11703
 
11704
@item @emph{Example}:
11705
See @code{RAND} and @code{IRAND} for examples.
11706
 
11707
@item @emph{Notes}:
11708
The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11709
initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11710
to generate pseudo-random numbers. Please note that in
11711
GNU Fortran, these two sets of intrinsics (@code{RAND},
11712
@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11713
@code{RANDOM_SEED} on the other hand) access two independent
11714
pseudo-random number generators.
11715
 
11716
@item @emph{See also}:
11717
@ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11718
 
11719
@end table
11720
 
11721
 
11722
 
11723
@node STAT
11724
@section @code{STAT} --- Get file status
11725
@fnindex STAT
11726
@cindex file system, file status
11727
 
11728
@table @asis
11729
@item @emph{Description}:
11730
This function returns information about a file. No permissions are required on
11731
the file itself, but execute (search) permission is required on all of the
11732
directories in path that lead to the file.
11733
 
11734
The elements that are obtained and stored in the array @code{VALUES}:
11735
@multitable @columnfractions .15 .70
11736
@item @code{VALUES(1)}   @tab  Device ID
11737
@item @code{VALUES(2)}   @tab  Inode number
11738
@item @code{VALUES(3)}   @tab  File mode
11739
@item @code{VALUES(4)}   @tab  Number of links
11740
@item @code{VALUES(5)}   @tab  Owner's uid
11741
@item @code{VALUES(6)}   @tab  Owner's gid
11742
@item @code{VALUES(7)}   @tab  ID of device containing directory entry for file (0 if not available)
11743
@item @code{VALUES(8)}   @tab  File size (bytes)
11744
@item @code{VALUES(9)}   @tab  Last access time
11745
@item @code{VALUES(10)}  @tab  Last modification time
11746
@item @code{VALUES(11)}  @tab  Last file status change time
11747
@item @code{VALUES(12)}  @tab  Preferred I/O block size (-1 if not available)
11748
@item @code{VALUES(13)}  @tab  Number of blocks allocated (-1 if not available)
11749
@end multitable
11750
 
11751
Not all these elements are relevant on all systems.
11752
If an element is not relevant, it is returned as 0.
11753
 
11754
This intrinsic is provided in both subroutine and function forms; however,
11755
only one form can be used in any given program unit.
11756
 
11757
@item @emph{Standard}:
11758
GNU extension
11759
 
11760
@item @emph{Class}:
11761
Subroutine, function
11762
 
11763
@item @emph{Syntax}:
11764
@multitable @columnfractions .80
11765
@item @code{CALL STAT(NAME, VALUES [, STATUS])}
11766
@item @code{STATUS = STAT(NAME, VALUES)}
11767
@end multitable
11768
 
11769
@item @emph{Arguments}:
11770
@multitable @columnfractions .15 .70
11771
@item @var{NAME}   @tab The type shall be @code{CHARACTER}, of the
11772
default kind and a valid path within the file system.
11773
@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11774
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11775
on success and a system specific error code otherwise.
11776
@end multitable
11777
 
11778
@item @emph{Example}:
11779
@smallexample
11780
PROGRAM test_stat
11781
  INTEGER, DIMENSION(13) :: buff
11782
  INTEGER :: status
11783
 
11784
  CALL STAT("/etc/passwd", buff, status)
11785
 
11786
  IF (status == 0) THEN
11787
    WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
11788
    WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
11789
    WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
11790
    WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
11791
    WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
11792
    WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
11793
    WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
11794
    WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
11795
    WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
11796
    WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
11797
    WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11798
    WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
11799
    WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11800
  END IF
11801
END PROGRAM
11802
@end smallexample
11803
 
11804
@item @emph{See also}:
11805
To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11806
@end table
11807
 
11808
 
11809
 
11810
@node STORAGE_SIZE
11811
@section @code{STORAGE_SIZE} --- Storage size in bits
11812
@fnindex STORAGE_SIZE
11813
@cindex storage size
11814
 
11815
@table @asis
11816
@item @emph{Description}:
11817
Returns the storage size of argument @var{A} in bits.
11818
@item @emph{Standard}:
11819
Fortran 2008 and later
11820
@item @emph{Class}:
11821
Inquiry function
11822
@item @emph{Syntax}:
11823
@code{RESULT = STORAGE_SIZE(A [, KIND])}
11824
 
11825
@item @emph{Arguments}:
11826
@multitable @columnfractions .15 .70
11827
@item @var{A} @tab Shall be a scalar or array of any type.
11828
@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11829
@end multitable
11830
 
11831
@item @emph{Return Value}:
11832
The result is a scalar integer with the kind type parameter specified by KIND
11833
(or default integer type if KIND is missing). The result value is the size
11834
expressed in bits for an element of an array that has the dynamic type and type
11835
parameters of A.
11836
 
11837
@item @emph{See also}:
11838
@ref{C_SIZEOF}, @ref{SIZEOF}
11839
@end table
11840
 
11841
 
11842
 
11843
@node SUM
11844
@section @code{SUM} --- Sum of array elements
11845
@fnindex SUM
11846
@cindex array, sum
11847
@cindex array, add elements
11848
@cindex array, conditionally add elements
11849
@cindex sum array elements
11850
 
11851
@table @asis
11852
@item @emph{Description}:
11853
Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11854
the corresponding element in @var{MASK} is @code{TRUE}.
11855
 
11856
@item @emph{Standard}:
11857
Fortran 95 and later
11858
 
11859
@item @emph{Class}:
11860
Transformational function
11861
 
11862
@item @emph{Syntax}:
11863
@multitable @columnfractions .80
11864
@item @code{RESULT = SUM(ARRAY[, MASK])}
11865
@item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11866
@end multitable
11867
 
11868
@item @emph{Arguments}:
11869
@multitable @columnfractions .15 .70
11870
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11871
@code{REAL} or @code{COMPLEX}.
11872
@item @var{DIM}   @tab (Optional) shall be a scalar of type
11873
@code{INTEGER} with a value in the range from 1 to n, where n
11874
equals the rank of @var{ARRAY}.
11875
@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
11876
and either be a scalar or an array of the same shape as @var{ARRAY}.
11877
@end multitable
11878
 
11879
@item @emph{Return value}:
11880
The result is of the same type as @var{ARRAY}.
11881
 
11882
If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11883
is returned. Otherwise, an array of rank n-1, where n equals the rank of
11884
@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11885
dropped is returned.
11886
 
11887
@item @emph{Example}:
11888
@smallexample
11889
PROGRAM test_sum
11890
  INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11891
  print *, SUM(x)                        ! all elements, sum = 15
11892
  print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
11893
END PROGRAM
11894
@end smallexample
11895
 
11896
@item @emph{See also}:
11897
@ref{PRODUCT}
11898
@end table
11899
 
11900
 
11901
 
11902
@node SYMLNK
11903
@section @code{SYMLNK} --- Create a symbolic link
11904
@fnindex SYMLNK
11905
@cindex file system, create link
11906
@cindex file system, soft link
11907
 
11908
@table @asis
11909
@item @emph{Description}:
11910
Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11911
character (@code{CHAR(0)}) can be used to mark the end of the names in
11912
@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11913
names are ignored.  If the @var{STATUS} argument is supplied, it
11914
contains 0 on success or a nonzero error code upon return; see
11915
@code{symlink(2)}.  If the system does not supply @code{symlink(2)},
11916
@code{ENOSYS} is returned.
11917
 
11918
This intrinsic is provided in both subroutine and function forms;
11919
however, only one form can be used in any given program unit.
11920
 
11921
@item @emph{Standard}:
11922
GNU extension
11923
 
11924
@item @emph{Class}:
11925
Subroutine, function
11926
 
11927
@item @emph{Syntax}:
11928
@multitable @columnfractions .80
11929
@item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11930
@item @code{STATUS = SYMLNK(PATH1, PATH2)}
11931
@end multitable
11932
 
11933
@item @emph{Arguments}:
11934
@multitable @columnfractions .15 .70
11935
@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11936
@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11937
@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11938
@end multitable
11939
 
11940
@item @emph{See also}:
11941
@ref{LINK}, @ref{UNLINK}
11942
 
11943
@end table
11944
 
11945
 
11946
 
11947
@node SYSTEM
11948
@section @code{SYSTEM} --- Execute a shell command
11949
@fnindex SYSTEM
11950
@cindex system, system call
11951
 
11952
@table @asis
11953
@item @emph{Description}:
11954
Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11955
argument @var{STATUS} is present, it contains the value returned by
11956
@code{system(3)}, which is presumably 0 if the shell command succeeded.
11957
Note that which shell is used to invoke the command is system-dependent
11958
and environment-dependent.
11959
 
11960
This intrinsic is provided in both subroutine and function forms;
11961
however, only one form can be used in any given program unit.
11962
 
11963
Note that the @code{system} function need not be thread-safe. It is
11964
the responsibility of the user to ensure that @code{system} is not
11965
called concurrently.
11966
 
11967
@item @emph{Standard}:
11968
GNU extension
11969
 
11970
@item @emph{Class}:
11971
Subroutine, function
11972
 
11973
@item @emph{Syntax}:
11974
@multitable @columnfractions .80
11975
@item @code{CALL SYSTEM(COMMAND [, STATUS])}
11976
@item @code{STATUS = SYSTEM(COMMAND)}
11977
@end multitable
11978
 
11979
@item @emph{Arguments}:
11980
@multitable @columnfractions .15 .70
11981
@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11982
@item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
11983
@end multitable
11984
 
11985
@item @emph{See also}:
11986
@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11987
and should considered in new code for future portability.
11988
@end table
11989
 
11990
 
11991
 
11992
@node SYSTEM_CLOCK
11993
@section @code{SYSTEM_CLOCK} --- Time function
11994
@fnindex SYSTEM_CLOCK
11995
@cindex time, clock ticks
11996
@cindex clock ticks
11997
 
11998
@table @asis
11999
@item @emph{Description}:
12000
Determines the @var{COUNT} of a processor clock since an unspecified
12001
time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
12002
the number of clock ticks per second.  If the platform supports a high
12003
resolution monotonic clock, that clock is used and can provide up to
12004
nanosecond resolution.  If a high resolution monotonic clock is not
12005
available, the implementation falls back to a potentially lower
12006
resolution realtime clock.
12007
 
12008
@var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
12009
arguments.  For @var{kind=8} arguments, @var{COUNT} represents
12010
nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
12011
milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
12012
@var{COUNT_MAX} are constant, however the particular values are
12013
specific to @command{gfortran}.
12014
 
12015
If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
12016
@var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
12017
 
12018
When running on a platform using the GNU C library (glibc), or a
12019
derivative thereof, the high resolution monotonic clock is available
12020
only when linking with the @var{rt} library.  This can be done
12021
explicitly by adding the @code{-lrt} flag when linking the
12022
application, but is also done implicitly when using OpenMP.
12023
 
12024
@item @emph{Standard}:
12025
Fortran 95 and later
12026
 
12027
@item @emph{Class}:
12028
Subroutine
12029
 
12030
@item @emph{Syntax}:
12031
@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12032
 
12033
@item @emph{Arguments}:
12034
@multitable @columnfractions .15 .70
12035
@item @var{COUNT}      @tab (Optional) shall be a scalar of type
12036
@code{INTEGER} with @code{INTENT(OUT)}.
12037
@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12038
@code{INTEGER} with @code{INTENT(OUT)}.
12039
@item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type
12040
@code{INTEGER} with @code{INTENT(OUT)}.
12041
@end multitable
12042
 
12043
@item @emph{Example}:
12044
@smallexample
12045
PROGRAM test_system_clock
12046
  INTEGER :: count, count_rate, count_max
12047
  CALL SYSTEM_CLOCK(count, count_rate, count_max)
12048
  WRITE(*,*) count, count_rate, count_max
12049
END PROGRAM
12050
@end smallexample
12051
 
12052
@item @emph{See also}:
12053
@ref{DATE_AND_TIME}, @ref{CPU_TIME}
12054
@end table
12055
 
12056
 
12057
 
12058
@node TAN
12059
@section @code{TAN} --- Tangent function
12060
@fnindex TAN
12061
@fnindex DTAN
12062
@cindex trigonometric function, tangent
12063
@cindex tangent
12064
 
12065
@table @asis
12066
@item @emph{Description}:
12067
@code{TAN(X)} computes the tangent of @var{X}.
12068
 
12069
@item @emph{Standard}:
12070
Fortran 77 and later, for a complex argument Fortran 2008 or later
12071
 
12072
@item @emph{Class}:
12073
Elemental function
12074
 
12075
@item @emph{Syntax}:
12076
@code{RESULT = TAN(X)}
12077
 
12078
@item @emph{Arguments}:
12079
@multitable @columnfractions .15 .70
12080
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12081
@end multitable
12082
 
12083
@item @emph{Return value}:
12084
The return value has same type and kind as @var{X}.
12085
 
12086
@item @emph{Example}:
12087
@smallexample
12088
program test_tan
12089
  real(8) :: x = 0.165_8
12090
  x = tan(x)
12091
end program test_tan
12092
@end smallexample
12093
 
12094
@item @emph{Specific names}:
12095
@multitable @columnfractions .20 .20 .20 .25
12096
@item Name            @tab Argument          @tab Return type     @tab Standard
12097
@item @code{TAN(X)}   @tab @code{REAL(4) X}  @tab @code{REAL(4)}  @tab Fortran 95 and later
12098
@item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab Fortran 95 and later
12099
@end multitable
12100
 
12101
@item @emph{See also}:
12102
@ref{ATAN}
12103
@end table
12104
 
12105
 
12106
 
12107
@node TANH
12108
@section @code{TANH} --- Hyperbolic tangent function
12109
@fnindex TANH
12110
@fnindex DTANH
12111
@cindex hyperbolic tangent
12112
@cindex hyperbolic function, tangent
12113
@cindex tangent, hyperbolic
12114
 
12115
@table @asis
12116
@item @emph{Description}:
12117
@code{TANH(X)} computes the hyperbolic tangent of @var{X}.
12118
 
12119
@item @emph{Standard}:
12120
Fortran 77 and later, for a complex argument Fortran 2008 or later
12121
 
12122
@item @emph{Class}:
12123
Elemental function
12124
 
12125
@item @emph{Syntax}:
12126
@code{X = TANH(X)}
12127
 
12128
@item @emph{Arguments}:
12129
@multitable @columnfractions .15 .70
12130
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12131
@end multitable
12132
 
12133
@item @emph{Return value}:
12134
The return value has same type and kind as @var{X}. If @var{X} is
12135
complex, the imaginary part of the result is in radians. If @var{X}
12136
is @code{REAL}, the return value lies in the range
12137
@math{ - 1 \leq tanh(x) \leq 1 }.
12138
 
12139
@item @emph{Example}:
12140
@smallexample
12141
program test_tanh
12142
  real(8) :: x = 2.1_8
12143
  x = tanh(x)
12144
end program test_tanh
12145
@end smallexample
12146
 
12147
@item @emph{Specific names}:
12148
@multitable @columnfractions .20 .20 .20 .25
12149
@item Name            @tab Argument          @tab Return type       @tab Standard
12150
@item @code{TANH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
12151
@item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
12152
@end multitable
12153
 
12154
@item @emph{See also}:
12155
@ref{ATANH}
12156
@end table
12157
 
12158
 
12159
 
12160
@node THIS_IMAGE
12161
@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12162
@fnindex THIS_IMAGE
12163
@cindex coarray, @code{THIS_IMAGE}
12164
@cindex images, index of this image
12165
 
12166
@table @asis
12167
@item @emph{Description}:
12168
Returns the cosubscript for this image.
12169
 
12170
@item @emph{Standard}:
12171
Fortran 2008 and later
12172
 
12173
@item @emph{Class}:
12174
Transformational function
12175
 
12176
@item @emph{Syntax}:
12177
@multitable @columnfractions .80
12178
@item @code{RESULT = THIS_IMAGE()}
12179
@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12180
@end multitable
12181
 
12182
@item @emph{Arguments}:
12183
@multitable @columnfractions .15 .70
12184
@item @var{COARRAY} @tab Coarray of any type  (optional; if @var{DIM}
12185
present, required).
12186
@item @var{DIM}     @tab default integer scalar (optional). If present,
12187
@var{DIM} shall be between one and the corank of @var{COARRAY}.
12188
@end multitable
12189
 
12190
 
12191
@item @emph{Return value}:
12192
Default integer. If @var{COARRAY} is not present, it is scalar and its value
12193
is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12194
a rank-1 array with corank elements is returned, containing the cosubscripts
12195
for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12196
a scalar is returned, with the value of the @var{DIM} element of
12197
@code{THIS_IMAGE(COARRAY)}.
12198
 
12199
@item @emph{Example}:
12200
@smallexample
12201
INTEGER :: value[*]
12202
INTEGER :: i
12203
value = THIS_IMAGE()
12204
SYNC ALL
12205
IF (THIS_IMAGE() == 1) THEN
12206
  DO i = 1, NUM_IMAGES()
12207
    WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12208
  END DO
12209
END IF
12210
@end smallexample
12211
 
12212
@item @emph{See also}:
12213
@ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12214
@end table
12215
 
12216
 
12217
 
12218
@node TIME
12219
@section @code{TIME} --- Time function
12220
@fnindex TIME
12221
@cindex time, current
12222
@cindex current time
12223
 
12224
@table @asis
12225
@item @emph{Description}:
12226
Returns the current time encoded as an integer (in the manner of the
12227
function @code{time(3)} in the C standard library). This value is
12228
suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12229
 
12230
This intrinsic is not fully portable, such as to systems with 32-bit
12231
@code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12232
the values returned by this intrinsic might be, or become, negative, or
12233
numerically less than previous values, during a single run of the
12234
compiled program.
12235
 
12236
See @ref{TIME8}, for information on a similar intrinsic that might be
12237
portable to more GNU Fortran implementations, though to fewer Fortran
12238
compilers.
12239
 
12240
@item @emph{Standard}:
12241
GNU extension
12242
 
12243
@item @emph{Class}:
12244
Function
12245
 
12246
@item @emph{Syntax}:
12247
@code{RESULT = TIME()}
12248
 
12249
@item @emph{Return value}:
12250
The return value is a scalar of type @code{INTEGER(4)}.
12251
 
12252
@item @emph{See also}:
12253
@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12254
 
12255
@end table
12256
 
12257
 
12258
 
12259
@node TIME8
12260
@section @code{TIME8} --- Time function (64-bit)
12261
@fnindex TIME8
12262
@cindex time, current
12263
@cindex current time
12264
 
12265
@table @asis
12266
@item @emph{Description}:
12267
Returns the current time encoded as an integer (in the manner of the
12268
function @code{time(3)} in the C standard library). This value is
12269
suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12270
 
12271
@emph{Warning:} this intrinsic does not increase the range of the timing
12272
values over that returned by @code{time(3)}. On a system with a 32-bit
12273
@code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12274
it is converted to a 64-bit @code{INTEGER(8)} value. That means
12275
overflows of the 32-bit value can still occur. Therefore, the values
12276
returned by this intrinsic might be or become negative or numerically
12277
less than previous values during a single run of the compiled program.
12278
 
12279
@item @emph{Standard}:
12280
GNU extension
12281
 
12282
@item @emph{Class}:
12283
Function
12284
 
12285
@item @emph{Syntax}:
12286
@code{RESULT = TIME8()}
12287
 
12288
@item @emph{Return value}:
12289
The return value is a scalar of type @code{INTEGER(8)}.
12290
 
12291
@item @emph{See also}:
12292
@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12293
 
12294
@end table
12295
 
12296
 
12297
 
12298
@node TINY
12299
@section @code{TINY} --- Smallest positive number of a real kind
12300
@fnindex TINY
12301
@cindex limits, smallest number
12302
@cindex model representation, smallest number
12303
 
12304
@table @asis
12305
@item @emph{Description}:
12306
@code{TINY(X)} returns the smallest positive (non zero) number
12307
in the model of the type of @code{X}.
12308
 
12309
@item @emph{Standard}:
12310
Fortran 95 and later
12311
 
12312
@item @emph{Class}:
12313
Inquiry function
12314
 
12315
@item @emph{Syntax}:
12316
@code{RESULT = TINY(X)}
12317
 
12318
@item @emph{Arguments}:
12319
@multitable @columnfractions .15 .70
12320
@item @var{X} @tab Shall be of type @code{REAL}.
12321
@end multitable
12322
 
12323
@item @emph{Return value}:
12324
The return value is of the same type and kind as @var{X}
12325
 
12326
@item @emph{Example}:
12327
See @code{HUGE} for an example.
12328
@end table
12329
 
12330
 
12331
 
12332
@node TRAILZ
12333
@section @code{TRAILZ} --- Number of trailing zero bits of an integer
12334
@fnindex TRAILZ
12335
@cindex zero bits
12336
 
12337
@table @asis
12338
@item @emph{Description}:
12339
@code{TRAILZ} returns the number of trailing zero bits of an integer.
12340
 
12341
@item @emph{Standard}:
12342
Fortran 2008 and later
12343
 
12344
@item @emph{Class}:
12345
Elemental function
12346
 
12347
@item @emph{Syntax}:
12348
@code{RESULT = TRAILZ(I)}
12349
 
12350
@item @emph{Arguments}:
12351
@multitable @columnfractions .15 .70
12352
@item @var{I} @tab Shall be of type @code{INTEGER}.
12353
@end multitable
12354
 
12355
@item @emph{Return value}:
12356
The type of the return value is the default @code{INTEGER}.
12357
If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12358
 
12359
@item @emph{Example}:
12360
@smallexample
12361
PROGRAM test_trailz
12362
  WRITE (*,*) TRAILZ(8)  ! prints 3
12363
END PROGRAM
12364
@end smallexample
12365
 
12366
@item @emph{See also}:
12367
@ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12368
@end table
12369
 
12370
 
12371
 
12372
@node TRANSFER
12373
@section @code{TRANSFER} --- Transfer bit patterns
12374
@fnindex TRANSFER
12375
@cindex bits, move
12376
@cindex type cast
12377
 
12378
@table @asis
12379
@item @emph{Description}:
12380
Interprets the bitwise representation of @var{SOURCE} in memory as if it
12381
is the representation of a variable or array of the same type and type
12382
parameters as @var{MOLD}.
12383
 
12384
This is approximately equivalent to the C concept of @emph{casting} one
12385
type to another.
12386
 
12387
@item @emph{Standard}:
12388
Fortran 95 and later
12389
 
12390
@item @emph{Class}:
12391
Transformational function
12392
 
12393
@item @emph{Syntax}:
12394
@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12395
 
12396
@item @emph{Arguments}:
12397
@multitable @columnfractions .15 .70
12398
@item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12399
@item @var{MOLD}   @tab Shall be a scalar or an array of any type.
12400
@item @var{SIZE}   @tab (Optional) shall be a scalar of type
12401
@code{INTEGER}.
12402
@end multitable
12403
 
12404
@item @emph{Return value}:
12405
The result has the same type as @var{MOLD}, with the bit level
12406
representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
12407
a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
12408
but @var{MOLD} is an array (of any size or shape), the result is a one-
12409
dimensional array of the minimum length needed to contain the entirety
12410
of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
12411
and @var{MOLD} is a scalar, the result is a scalar.
12412
 
12413
If the bitwise representation of the result is longer than that of
12414
@var{SOURCE}, then the leading bits of the result correspond to those of
12415
@var{SOURCE} and any trailing bits are filled arbitrarily.
12416
 
12417
When the resulting bit representation does not correspond to a valid
12418
representation of a variable of the same type as @var{MOLD}, the results
12419
are undefined, and subsequent operations on the result cannot be
12420
guaranteed to produce sensible behavior.  For example, it is possible to
12421
create @code{LOGICAL} variables for which @code{@var{VAR}} and
12422
@code{.NOT.@var{VAR}} both appear to be true.
12423
 
12424
@item @emph{Example}:
12425
@smallexample
12426
PROGRAM test_transfer
12427
  integer :: x = 2143289344
12428
  print *, transfer(x, 1.0)    ! prints "NaN" on i686
12429
END PROGRAM
12430
@end smallexample
12431
@end table
12432
 
12433
 
12434
 
12435
@node TRANSPOSE
12436
@section @code{TRANSPOSE} --- Transpose an array of rank two
12437
@fnindex TRANSPOSE
12438
@cindex array, transpose
12439
@cindex matrix, transpose
12440
@cindex transpose
12441
 
12442
@table @asis
12443
@item @emph{Description}:
12444
Transpose an array of rank two. Element (i, j) of the result has the value
12445
@code{MATRIX(j, i)}, for all i, j.
12446
 
12447
@item @emph{Standard}:
12448
Fortran 95 and later
12449
 
12450
@item @emph{Class}:
12451
Transformational function
12452
 
12453
@item @emph{Syntax}:
12454
@code{RESULT = TRANSPOSE(MATRIX)}
12455
 
12456
@item @emph{Arguments}:
12457
@multitable @columnfractions .15 .70
12458
@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12459
@end multitable
12460
 
12461
@item @emph{Return value}:
12462
The result has the same type as @var{MATRIX}, and has shape
12463
@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12464
@end table
12465
 
12466
 
12467
 
12468
@node TRIM
12469
@section @code{TRIM} --- Remove trailing blank characters of a string
12470
@fnindex TRIM
12471
@cindex string, remove trailing whitespace
12472
 
12473
@table @asis
12474
@item @emph{Description}:
12475
Removes trailing blank characters of a string.
12476
 
12477
@item @emph{Standard}:
12478
Fortran 95 and later
12479
 
12480
@item @emph{Class}:
12481
Transformational function
12482
 
12483
@item @emph{Syntax}:
12484
@code{RESULT = TRIM(STRING)}
12485
 
12486
@item @emph{Arguments}:
12487
@multitable @columnfractions .15 .70
12488
@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12489
@end multitable
12490
 
12491
@item @emph{Return value}:
12492
A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12493
less the number of trailing blanks.
12494
 
12495
@item @emph{Example}:
12496
@smallexample
12497
PROGRAM test_trim
12498
  CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
12499
  WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
12500
END PROGRAM
12501
@end smallexample
12502
 
12503
@item @emph{See also}:
12504
@ref{ADJUSTL}, @ref{ADJUSTR}
12505
@end table
12506
 
12507
 
12508
 
12509
@node TTYNAM
12510
@section @code{TTYNAM} --- Get the name of a terminal device.
12511
@fnindex TTYNAM
12512
@cindex system, terminal
12513
 
12514
@table @asis
12515
@item @emph{Description}:
12516
Get the name of a terminal device. For more information,
12517
see @code{ttyname(3)}.
12518
 
12519
This intrinsic is provided in both subroutine and function forms;
12520
however, only one form can be used in any given program unit.
12521
 
12522
@item @emph{Standard}:
12523
GNU extension
12524
 
12525
@item @emph{Class}:
12526
Subroutine, function
12527
 
12528
@item @emph{Syntax}:
12529
@multitable @columnfractions .80
12530
@item @code{CALL TTYNAM(UNIT, NAME)}
12531
@item @code{NAME = TTYNAM(UNIT)}
12532
@end multitable
12533
 
12534
@item @emph{Arguments}:
12535
@multitable @columnfractions .15 .70
12536
@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12537
@item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12538
@end multitable
12539
 
12540
@item @emph{Example}:
12541
@smallexample
12542
PROGRAM test_ttynam
12543
  INTEGER :: unit
12544
  DO unit = 1, 10
12545
    IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12546
  END DO
12547
END PROGRAM
12548
@end smallexample
12549
 
12550
@item @emph{See also}:
12551
@ref{ISATTY}
12552
@end table
12553
 
12554
 
12555
 
12556
@node UBOUND
12557
@section @code{UBOUND} --- Upper dimension bounds of an array
12558
@fnindex UBOUND
12559
@cindex array, upper bound
12560
 
12561
@table @asis
12562
@item @emph{Description}:
12563
Returns the upper bounds of an array, or a single upper bound
12564
along the @var{DIM} dimension.
12565
@item @emph{Standard}:
12566
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12567
 
12568
@item @emph{Class}:
12569
Inquiry function
12570
 
12571
@item @emph{Syntax}:
12572
@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12573
 
12574
@item @emph{Arguments}:
12575
@multitable @columnfractions .15 .70
12576
@item @var{ARRAY} @tab Shall be an array, of any type.
12577
@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12578
@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12579
expression indicating the kind parameter of the result.
12580
@end multitable
12581
 
12582
@item @emph{Return value}:
12583
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12584
@var{KIND} is absent, the return value is of default integer kind.
12585
If @var{DIM} is absent, the result is an array of the upper bounds of
12586
@var{ARRAY}.  If @var{DIM} is present, the result is a scalar
12587
corresponding to the upper bound of the array along that dimension.  If
12588
@var{ARRAY} is an expression rather than a whole array or array
12589
structure component, or if it has a zero extent along the relevant
12590
dimension, the upper bound is taken to be the number of elements along
12591
the relevant dimension.
12592
 
12593
@item @emph{See also}:
12594
@ref{LBOUND}, @ref{LCOBOUND}
12595
@end table
12596
 
12597
 
12598
 
12599
@node UCOBOUND
12600
@section @code{UCOBOUND} --- Upper codimension bounds of an array
12601
@fnindex UCOBOUND
12602
@cindex coarray, upper bound
12603
 
12604
@table @asis
12605
@item @emph{Description}:
12606
Returns the upper cobounds of a coarray, or a single upper cobound
12607
along the @var{DIM} codimension.
12608
@item @emph{Standard}:
12609
Fortran 2008 and later
12610
 
12611
@item @emph{Class}:
12612
Inquiry function
12613
 
12614
@item @emph{Syntax}:
12615
@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12616
 
12617
@item @emph{Arguments}:
12618
@multitable @columnfractions .15 .70
12619
@item @var{ARRAY} @tab Shall be an coarray, of any type.
12620
@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12621
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12622
expression indicating the kind parameter of the result.
12623
@end multitable
12624
 
12625
@item @emph{Return value}:
12626
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12627
@var{KIND} is absent, the return value is of default integer kind.
12628
If @var{DIM} is absent, the result is an array of the lower cobounds of
12629
@var{COARRAY}.  If @var{DIM} is present, the result is a scalar
12630
corresponding to the lower cobound of the array along that codimension.
12631
 
12632
@item @emph{See also}:
12633
@ref{LCOBOUND}, @ref{LBOUND}
12634
@end table
12635
 
12636
 
12637
 
12638
@node UMASK
12639
@section @code{UMASK} --- Set the file creation mask
12640
@fnindex UMASK
12641
@cindex file system, file creation mask
12642
 
12643
@table @asis
12644
@item @emph{Description}:
12645
Sets the file creation mask to @var{MASK}. If called as a function, it
12646
returns the old value. If called as a subroutine and argument @var{OLD}
12647
if it is supplied, it is set to the old value. See @code{umask(2)}.
12648
 
12649
@item @emph{Standard}:
12650
GNU extension
12651
 
12652
@item @emph{Class}:
12653
Subroutine, function
12654
 
12655
@item @emph{Syntax}:
12656
@multitable @columnfractions .80
12657
@item @code{CALL UMASK(MASK [, OLD])}
12658
@item @code{OLD = UMASK(MASK)}
12659
@end multitable
12660
 
12661
@item @emph{Arguments}:
12662
@multitable @columnfractions .15 .70
12663
@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12664
@item @var{OLD} @tab (Optional) Shall be a scalar of type
12665
@code{INTEGER}.
12666
@end multitable
12667
 
12668
@end table
12669
 
12670
 
12671
 
12672
@node UNLINK
12673
@section @code{UNLINK} --- Remove a file from the file system
12674
@fnindex UNLINK
12675
@cindex file system, remove file
12676
 
12677
@table @asis
12678
@item @emph{Description}:
12679
Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12680
used to mark the end of the name in @var{PATH}; otherwise, trailing
12681
blanks in the file name are ignored.  If the @var{STATUS} argument is
12682
supplied, it contains 0 on success or a nonzero error code upon return;
12683
see @code{unlink(2)}.
12684
 
12685
This intrinsic is provided in both subroutine and function forms;
12686
however, only one form can be used in any given program unit.
12687
 
12688
@item @emph{Standard}:
12689
GNU extension
12690
 
12691
@item @emph{Class}:
12692
Subroutine, function
12693
 
12694
@item @emph{Syntax}:
12695
@multitable @columnfractions .80
12696
@item @code{CALL UNLINK(PATH [, STATUS])}
12697
@item @code{STATUS = UNLINK(PATH)}
12698
@end multitable
12699
 
12700
@item @emph{Arguments}:
12701
@multitable @columnfractions .15 .70
12702
@item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12703
@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12704
@end multitable
12705
 
12706
@item @emph{See also}:
12707
@ref{LINK}, @ref{SYMLNK}
12708
@end table
12709
 
12710
 
12711
 
12712
@node UNPACK
12713
@section @code{UNPACK} --- Unpack an array of rank one into an array
12714
@fnindex UNPACK
12715
@cindex array, unpacking
12716
@cindex array, increase dimension
12717
@cindex array, scatter elements
12718
 
12719
@table @asis
12720
@item @emph{Description}:
12721
Store the elements of @var{VECTOR} in an array of higher rank.
12722
 
12723
@item @emph{Standard}:
12724
Fortran 95 and later
12725
 
12726
@item @emph{Class}:
12727
Transformational function
12728
 
12729
@item @emph{Syntax}:
12730
@code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12731
 
12732
@item @emph{Arguments}:
12733
@multitable @columnfractions .15 .70
12734
@item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12735
shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12736
@item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
12737
@item @var{FIELD}  @tab Shall be of the same type as @var{VECTOR} and have
12738
the same shape as @var{MASK}.
12739
@end multitable
12740
 
12741
@item @emph{Return value}:
12742
The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12743
of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12744
 
12745
@item @emph{Example}:
12746
@smallexample
12747
PROGRAM test_unpack
12748
  integer :: vector(2)  = (/1,1/)
12749
  logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12750
  integer :: field(2,2) = 0, unity(2,2)
12751
 
12752
  ! result: unity matrix
12753
  unity = unpack(vector, reshape(mask, (/2,2/)), field)
12754
END PROGRAM
12755
@end smallexample
12756
 
12757
@item @emph{See also}:
12758
@ref{PACK}, @ref{SPREAD}
12759
@end table
12760
 
12761
 
12762
 
12763
@node VERIFY
12764
@section @code{VERIFY} --- Scan a string for characters not a given set
12765
@fnindex VERIFY
12766
@cindex string, find missing set
12767
 
12768
@table @asis
12769
@item @emph{Description}:
12770
Verifies that all the characters in @var{STRING} belong to the set of
12771
characters in @var{SET}.
12772
 
12773
If @var{BACK} is either absent or equals @code{FALSE}, this function
12774
returns the position of the leftmost character of @var{STRING} that is
12775
not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12776
position is returned. If all characters of @var{STRING} are found in
12777
@var{SET}, the result is zero.
12778
 
12779
@item @emph{Standard}:
12780
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12781
 
12782
@item @emph{Class}:
12783
Elemental function
12784
 
12785
@item @emph{Syntax}:
12786
@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12787
 
12788
@item @emph{Arguments}:
12789
@multitable @columnfractions .15 .70
12790
@item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12791
@item @var{SET}    @tab Shall be of type @code{CHARACTER}.
12792
@item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
12793
@item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
12794
expression indicating the kind parameter of the result.
12795
@end multitable
12796
 
12797
@item @emph{Return value}:
12798
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12799
@var{KIND} is absent, the return value is of default integer kind.
12800
 
12801
@item @emph{Example}:
12802
@smallexample
12803
PROGRAM test_verify
12804
  WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
12805
  WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
12806
  WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
12807
  WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
12808
  WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
12809
END PROGRAM
12810
@end smallexample
12811
 
12812
@item @emph{See also}:
12813
@ref{SCAN}, @ref{INDEX intrinsic}
12814
@end table
12815
 
12816
 
12817
 
12818
@node XOR
12819
@section @code{XOR} --- Bitwise logical exclusive OR
12820
@fnindex XOR
12821
@cindex bitwise logical exclusive or
12822
@cindex logical exclusive or, bitwise
12823
 
12824
@table @asis
12825
@item @emph{Description}:
12826
Bitwise logical exclusive or.
12827
 
12828
This intrinsic routine is provided for backwards compatibility with
12829
GNU Fortran 77.  For integer arguments, programmers should consider
12830
the use of the @ref{IEOR} intrinsic and for logical arguments the
12831
@code{.NEQV.} operator, which are both defined by the Fortran standard.
12832
 
12833
@item @emph{Standard}:
12834
GNU extension
12835
 
12836
@item @emph{Class}:
12837
Function
12838
 
12839
@item @emph{Syntax}:
12840
@code{RESULT = XOR(I, J)}
12841
 
12842
@item @emph{Arguments}:
12843
@multitable @columnfractions .15 .70
12844
@item @var{I} @tab The type shall be either  a scalar @code{INTEGER}
12845
type or a scalar @code{LOGICAL} type.
12846
@item @var{J} @tab The type shall be the same as the type of @var{I}.
12847
@end multitable
12848
 
12849
@item @emph{Return value}:
12850
The return type is either a scalar @code{INTEGER} or a scalar
12851
@code{LOGICAL}.  If the kind type parameters differ, then the
12852
smaller kind type is implicitly converted to larger kind, and the
12853
return has the larger kind.
12854
 
12855
@item @emph{Example}:
12856
@smallexample
12857
PROGRAM test_xor
12858
  LOGICAL :: T = .TRUE., F = .FALSE.
12859
  INTEGER :: a, b
12860
  DATA a / Z'F' /, b / Z'3' /
12861
 
12862
  WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12863
  WRITE (*,*) XOR(a, b)
12864
END PROGRAM
12865
@end smallexample
12866
 
12867
@item @emph{See also}:
12868
Fortran 95 elemental function: @ref{IEOR}
12869
@end table
12870
 
12871
 
12872
 
12873
@node Intrinsic Modules
12874
@chapter Intrinsic Modules
12875
@cindex intrinsic Modules
12876
 
12877
@menu
12878
* ISO_FORTRAN_ENV::
12879
* ISO_C_BINDING::
12880
* OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12881
@end menu
12882
 
12883
@node ISO_FORTRAN_ENV
12884
@section @code{ISO_FORTRAN_ENV}
12885
@table @asis
12886
@item @emph{Standard}:
12887
Fortran 2003 and later, except when otherwise noted
12888
@end table
12889
 
12890
The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12891
named constants:
12892
 
12893
@table @asis
12894
@item @code{ATOMIC_INT_KIND}:
12895
Default-kind integer constant to be used as kind parameter when defining
12896
integer variables used in atomic operations. (Fortran 2008 or later.)
12897
 
12898
@item @code{ATOMIC_LOGICAL_KIND}:
12899
Default-kind integer constant to be used as kind parameter when defining
12900
logical variables used in atomic operations. (Fortran 2008 or later.)
12901
 
12902
@item @code{CHARACTER_KINDS}:
12903
Default-kind integer constant array of rank one containing the supported kind
12904
parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12905
 
12906
@item @code{CHARACTER_STORAGE_SIZE}:
12907
Size in bits of the character storage unit.
12908
 
12909
@item @code{ERROR_UNIT}:
12910
Identifies the preconnected unit used for error reporting.
12911
 
12912
@item @code{FILE_STORAGE_SIZE}:
12913
Size in bits of the file-storage unit.
12914
 
12915
@item @code{INPUT_UNIT}:
12916
Identifies the preconnected unit identified by the asterisk
12917
(@code{*}) in @code{READ} statement.
12918
 
12919
@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12920
Kind type parameters to specify an INTEGER type with a storage
12921
size of 16, 32, and 64 bits. It is negative if a target platform
12922
does not support the particular kind. (Fortran 2008 or later.)
12923
 
12924
@item @code{INTEGER_KINDS}:
12925
Default-kind integer constant array of rank one containing the supported kind
12926
parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12927
 
12928
@item @code{IOSTAT_END}:
12929
The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12930
an input/output statement if an end-of-file condition occurred.
12931
 
12932
@item @code{IOSTAT_EOR}:
12933
The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12934
an input/output statement if an end-of-record condition occurred.
12935
 
12936
@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12937
Scalar default-integer constant, used by @code{INQUIRE} for the
12938
@code{IOSTAT=} specifier to denote an that a unit number identifies an
12939
internal unit. (Fortran 2008 or later.)
12940
 
12941
@item @code{NUMERIC_STORAGE_SIZE}:
12942
The size in bits of the numeric storage unit.
12943
 
12944
@item @code{LOGICAL_KINDS}:
12945
Default-kind integer constant array of rank one containing the supported kind
12946
parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12947
 
12948
@item @code{OUTPUT_UNIT}:
12949
Identifies the preconnected unit identified by the asterisk
12950
(@code{*}) in @code{WRITE} statement.
12951
 
12952
@item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12953
Kind type parameters to specify a REAL type with a storage
12954
size of 32, 64, and 128 bits. It is negative if a target platform
12955
does not support the particular kind. (Fortran 2008 or later.)
12956
 
12957
@item @code{REAL_KINDS}:
12958
Default-kind integer constant array of rank one containing the supported kind
12959
parameters of the @code{REAL} type. (Fortran 2008 or later.)
12960
 
12961
@item @code{STAT_LOCKED}:
12962
Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12963
denote that the lock variable is locked by the executing image. (Fortran 2008
12964
or later.)
12965
 
12966
@item @code{STAT_LOCKED_OTHER_IMAGE}:
12967
Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12968
denote that the lock variable is locked by another image. (Fortran 2008 or
12969
later.)
12970
 
12971
@item @code{STAT_STOPPED_IMAGE}:
12972
Positive, scalar default-integer constant used as STAT= return value if the
12973
argument in the statement requires synchronisation with an image, which has
12974
initiated the termination of the execution. (Fortran 2008 or later.)
12975
 
12976
@item @code{STAT_UNLOCKED}:
12977
Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12978
denote that the lock variable is unlocked. (Fortran 2008 or later.)
12979
@end table
12980
 
12981
The module provides the following derived type:
12982
 
12983
@table @asis
12984
@item @code{LOCK_TYPE}:
12985
Derived type with private components to be use with the @code{LOCK} and
12986
@code{UNLOCK} statement. A variable of its type has to be always declared
12987
as coarray and may not appear in a variable-definition context.
12988
(Fortran 2008 or later.)
12989
@end table
12990
 
12991
The module also provides the following intrinsic procedures:
12992
@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12993
 
12994
 
12995
 
12996
@node ISO_C_BINDING
12997
@section @code{ISO_C_BINDING}
12998
@table @asis
12999
@item @emph{Standard}:
13000
Fortran 2003 and later, GNU extensions
13001
@end table
13002
 
13003
The following intrinsic procedures are provided by the module; their
13004
definition can be found in the section Intrinsic Procedures of this
13005
manual.
13006
 
13007
@table @asis
13008
@item @code{C_ASSOCIATED}
13009
@item @code{C_F_POINTER}
13010
@item @code{C_F_PROCPOINTER}
13011
@item @code{C_FUNLOC}
13012
@item @code{C_LOC}
13013
@item @code{C_SIZEOF}
13014
@end table
13015
@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13016
@c don't really know why.
13017
 
13018
The @code{ISO_C_BINDING} module provides the following named constants of
13019
type default integer, which can be used as KIND type parameters.
13020
 
13021
In addition to the integer named constants required by the Fortran 2003
13022
standard, GNU Fortran provides as an extension named constants for the
13023
128-bit integer types supported by the C compiler: @code{C_INT128_T,
13024
C_INT_LEAST128_T, C_INT_FAST128_T}. Furthermore, if @code{__float} is
13025
supported in C, the named constants @code{C_FLOAT128, C_FLOAT128_COMPLEX}
13026
are defined.
13027
 
13028
@multitable @columnfractions .15 .35 .35 .35
13029
@item Fortran Type  @tab Named constant         @tab C type                                @tab Extension
13030
@item @code{INTEGER}@tab @code{C_INT}           @tab @code{int}
13031
@item @code{INTEGER}@tab @code{C_SHORT}         @tab @code{short int}
13032
@item @code{INTEGER}@tab @code{C_LONG}          @tab @code{long int}
13033
@item @code{INTEGER}@tab @code{C_LONG_LONG}     @tab @code{long long int}
13034
@item @code{INTEGER}@tab @code{C_SIGNED_CHAR}   @tab @code{signed char}/@code{unsigned char}
13035
@item @code{INTEGER}@tab @code{C_SIZE_T}        @tab @code{size_t}
13036
@item @code{INTEGER}@tab @code{C_INT8_T}        @tab @code{int8_t}
13037
@item @code{INTEGER}@tab @code{C_INT16_T}       @tab @code{int16_t}
13038
@item @code{INTEGER}@tab @code{C_INT32_T}       @tab @code{int32_t}
13039
@item @code{INTEGER}@tab @code{C_INT64_T}       @tab @code{int64_t}
13040
@item @code{INTEGER}@tab @code{C_INT128_T}      @tab @code{int128_t}                      @tab Ext.
13041
@item @code{INTEGER}@tab @code{C_INT_LEAST8_T}  @tab @code{int_least8_t}
13042
@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13043
@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13044
@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13045
@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t}                @tab Ext.
13046
@item @code{INTEGER}@tab @code{C_INT_FAST8_T}   @tab @code{int_fast8_t}
13047
@item @code{INTEGER}@tab @code{C_INT_FAST16_T}  @tab @code{int_fast16_t}
13048
@item @code{INTEGER}@tab @code{C_INT_FAST32_T}  @tab @code{int_fast32_t}
13049
@item @code{INTEGER}@tab @code{C_INT_FAST64_T}  @tab @code{int_fast64_t}
13050
@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t}                 @tab Ext.
13051
@item @code{INTEGER}@tab @code{C_INTMAX_T}      @tab @code{intmax_t}
13052
@item @code{INTEGER}@tab @code{C_INTPTR_T}      @tab @code{intptr_t}
13053
@item @code{REAL}   @tab @code{C_FLOAT}         @tab @code{float}
13054
@item @code{REAL}   @tab @code{C_DOUBLE}        @tab @code{double}
13055
@item @code{REAL}   @tab @code{C_LONG_DOUBLE}   @tab @code{long double}
13056
@item @code{REAL}   @tab @code{C_FLOAT128}      @tab @code{__float128}                    @tab Ext.
13057
@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13058
@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13059
@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13060
@item @code{REAL}   @tab @code{C_FLOAT128_COMPLEX}   @tab @code{__float128 _Complex}      @tab Ext.
13061
@item @code{LOGICAL}@tab @code{C_BOOL}          @tab @code{_Bool}
13062
@item @code{CHARACTER}@tab @code{C_CHAR}        @tab @code{char}
13063
@end multitable
13064
 
13065
Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13066
are defined.
13067
 
13068
@multitable @columnfractions .20 .45 .15
13069
@item Name                     @tab C definition    @tab Value
13070
@item @code{C_NULL_CHAR}       @tab null character  @tab @code{'\0'}
13071
@item @code{C_ALERT}           @tab alert           @tab @code{'\a'}
13072
@item @code{C_BACKSPACE}       @tab backspace       @tab @code{'\b'}
13073
@item @code{C_FORM_FEED}       @tab form feed       @tab @code{'\f'}
13074
@item @code{C_NEW_LINE}        @tab new line        @tab @code{'\n'}
13075
@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13076
@item @code{C_HORIZONTAL_TAB}  @tab horizontal tab  @tab @code{'\t'}
13077
@item @code{C_VERTICAL_TAB}    @tab vertical tab    @tab @code{'\v'}
13078
@end multitable
13079
 
13080
Moreover, the following two named constants are defined:
13081
 
13082
@multitable @columnfractions .20 .80
13083
@item Name                 @tab Type
13084
@item @code{C_NULL_PTR}    @tab @code{C_PTR}
13085
@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13086
@end multitable
13087
 
13088
Both are equivalent to the value @code{NULL} in C.
13089
 
13090
@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
13091
@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
13092
@table @asis
13093
@item @emph{Standard}:
13094
OpenMP Application Program Interface v3.1
13095
@end table
13096
 
13097
 
13098
The OpenMP Fortran runtime library routines are provided both in
13099
a form of two Fortran 90 modules, named @code{OMP_LIB} and
13100
@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
13101
@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
13102
in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
13103
the named constants defined in the modules are listed
13104
below.
13105
 
13106
For details refer to the actual
13107
@uref{http://www.openmp.org/mp-documents/spec31.pdf,
13108
OpenMP Application Program Interface v3.1}.
13109
 
13110
@code{OMP_LIB_KINDS} provides the following scalar default-integer
13111
named constants:
13112
 
13113
@table @asis
13114
@item @code{omp_lock_kind}
13115
@item @code{omp_nest_lock_kind}
13116
@item @code{omp_sched_kind}
13117
@end table
13118
 
13119
@code{OMP_LIB} provides the scalar default-integer
13120
named constant @code{openmp_version} with a value of the form
13121
@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
13122
of the OpenMP version; for OpenMP v3.1 the value is @code{201107}.
13123
 
13124
And the following scalar integer named constants of the
13125
kind @code{omp_sched_kind}:
13126
 
13127
@table @asis
13128
@item @code{omp_sched_static}
13129
@item @code{omp_sched_dynamic}
13130
@item @code{omp_sched_guided}
13131
@item @code{omp_sched_auto}
13132
@end table

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.