1@ignore
2Copyright (C) 2005-2021 Free Software Foundation, Inc.
3This is part of the GNU Fortran manual.
4For copying conditions, see the file gfortran.texi.
5
6Permission is granted to copy, distribute and/or modify this document
7under the terms of the GNU Free Documentation License, Version 1.3 or
8any later version published by the Free Software Foundation; with the
9Invariant Sections being ``Funding Free Software'', the Front-Cover
10Texts being (a) (see below), and with the Back-Cover Texts being (b)
11(see below).  A copy of the license is included in the gfdl(7) man page.
12
13
14Some basic guidelines for editing this document:
15
16  (1) The intrinsic procedures are to be listed in alphabetical order.
17  (2) The generic name is to be used.
18  (3) The specific names are included in the function index and in a
19      table at the end of the node (See ABS entry).
20  (4) Try to maintain the same style for each entry.
21
22
23@end ignore
24
25@tex
26\gdef\acosd{\mathop{\rm acosd}\nolimits}
27\gdef\asind{\mathop{\rm asind}\nolimits}
28\gdef\atand{\mathop{\rm atand}\nolimits}
29\gdef\acos{\mathop{\rm acos}\nolimits}
30\gdef\asin{\mathop{\rm asin}\nolimits}
31\gdef\atan{\mathop{\rm atan}\nolimits}
32\gdef\acosh{\mathop{\rm acosh}\nolimits}
33\gdef\asinh{\mathop{\rm asinh}\nolimits}
34\gdef\atanh{\mathop{\rm atanh}\nolimits}
35\gdef\cosd{\mathop{\rm cosd}\nolimits}
36@end tex
37
38
39@node Intrinsic Procedures
40@chapter Intrinsic Procedures
41@cindex intrinsic procedures
42
43@menu
44* Introduction:         Introduction to Intrinsics
45* @code{ABORT}:         ABORT,     Abort the program
46* @code{ABS}:           ABS,       Absolute value
47* @code{ACCESS}:        ACCESS,    Checks file access modes
48* @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
49* @code{ACOS}:          ACOS,      Arccosine function
50* @code{ACOSD}:         ACOSD,     Arccosine function, degrees
51* @code{ACOSH}:         ACOSH,     Inverse hyperbolic cosine function
52* @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
53* @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
54* @code{AIMAG}:         AIMAG,     Imaginary part of complex number
55* @code{AINT}:          AINT,      Truncate to a whole number
56* @code{ALARM}:         ALARM,     Set an alarm clock
57* @code{ALL}:           ALL,       Determine if all values are true
58* @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
59* @code{AND}:           AND,       Bitwise logical AND
60* @code{ANINT}:         ANINT,     Nearest whole number
61* @code{ANY}:           ANY,       Determine if any values are true
62* @code{ASIN}:          ASIN,      Arcsine function
63* @code{ASIND}:         ASIND,     Arcsine function, degrees
64* @code{ASINH}:         ASINH,     Inverse hyperbolic sine function
65* @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
66* @code{ATAN}:          ATAN,      Arctangent function
67* @code{ATAND}:         ATAND,     Arctangent function, degrees
68* @code{ATAN2}:         ATAN2,     Arctangent function
69* @code{ATAN2D}:        ATAN2D,    Arctangent function, degrees
70* @code{ATANH}:         ATANH,     Inverse hyperbolic tangent function
71* @code{ATOMIC_ADD}:    ATOMIC_ADD, Atomic ADD operation
72* @code{ATOMIC_AND}:    ATOMIC_AND, Atomic bitwise AND operation
73* @code{ATOMIC_CAS}:    ATOMIC_CAS, Atomic compare and swap
74* @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
75* @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
76* @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
77* @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
78* @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
79* @code{ATOMIC_OR}:     ATOMIC_OR, Atomic bitwise OR operation
80* @code{ATOMIC_REF}:    ATOMIC_REF, Obtaining the value of a variable atomically
81* @code{ATOMIC_XOR}:    ATOMIC_XOR, Atomic bitwise OR operation
82* @code{BACKTRACE}:     BACKTRACE, Show a backtrace
83* @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
84* @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
85* @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
86* @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
87* @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
88* @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
89* @code{BGE}:           BGE,       Bitwise greater than or equal to
90* @code{BGT}:           BGT,       Bitwise greater than
91* @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
92* @code{BLE}:           BLE,       Bitwise less than or equal to
93* @code{BLT}:           BLT,       Bitwise less than
94* @code{BTEST}:         BTEST,     Bit test function
95* @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
96* @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
97* @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
98* @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
99* @code{C_LOC}:         C_LOC,     Obtain the C address of an object
100* @code{C_SIZEOF}:      C_SIZEOF,  Size in bytes of an expression
101* @code{CEILING}:       CEILING,   Integer ceiling function
102* @code{CHAR}:          CHAR,      Integer-to-character conversion function
103* @code{CHDIR}:         CHDIR,     Change working directory
104* @code{CHMOD}:         CHMOD,     Change access permissions of files
105* @code{CMPLX}:         CMPLX,     Complex conversion function
106* @code{CO_BROADCAST}:  CO_BROADCAST, Copy a value to all images the current set of images
107* @code{CO_MAX}:        CO_MAX,    Maximal value on the current set of images
108* @code{CO_MIN}:        CO_MIN,    Minimal value on the current set of images
109* @code{CO_REDUCE}:     CO_REDUCE, Reduction of values on the current set of images
110* @code{CO_SUM}:        CO_SUM,    Sum of values on the current set of images
111* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
112* @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
113* @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
114* @code{COMPLEX}:       COMPLEX,   Complex conversion function
115* @code{CONJG}:         CONJG,     Complex conjugate function
116* @code{COS}:           COS,       Cosine function
117* @code{COSD}:          COSD,      Cosine function, degrees
118* @code{COSH}:          COSH,      Hyperbolic cosine function
119* @code{COTAN}:         COTAN,     Cotangent function
120* @code{COTAND}:        COTAND,    Cotangent function, degrees
121* @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
122* @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
123* @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
124* @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
125* @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
126* @code{DBLE}:          DBLE,      Double precision conversion function
127* @code{DCMPLX}:        DCMPLX,    Double complex conversion function
128* @code{DIGITS}:        DIGITS,    Significant digits function
129* @code{DIM}:           DIM,       Positive difference
130* @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
131* @code{DPROD}:         DPROD,     Double product function
132* @code{DREAL}:         DREAL,     Double real part function
133* @code{DSHIFTL}:       DSHIFTL,   Combined left shift
134* @code{DSHIFTR}:       DSHIFTR,   Combined right shift
135* @code{DTIME}:         DTIME,     Execution time subroutine (or function)
136* @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
137* @code{EPSILON}:       EPSILON,   Epsilon function
138* @code{ERF}:           ERF,       Error function
139* @code{ERFC}:          ERFC,      Complementary error function
140* @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
141* @code{ETIME}:         ETIME,     Execution time subroutine (or function)
142* @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
143* @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
144* @code{EXIT}:          EXIT,      Exit the program with status.
145* @code{EXP}:           EXP,       Exponential function
146* @code{EXPONENT}:      EXPONENT,  Exponent function
147* @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF,  Query dynamic type for extension
148* @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
149* @code{FGET}:          FGET,      Read a single character in stream mode from stdin
150* @code{FGETC}:         FGETC,     Read a single character in stream mode
151* @code{FINDLOC}:       FINDLOC,   Search an array for a value
152* @code{FLOOR}:         FLOOR,     Integer floor function
153* @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
154* @code{FNUM}:          FNUM,      File number function
155* @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
156* @code{FPUTC}:         FPUTC,     Write a single character in stream mode
157* @code{FRACTION}:      FRACTION,  Fractional part of the model representation
158* @code{FREE}:          FREE,      Memory de-allocation subroutine
159* @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
160* @code{FSTAT}:         FSTAT,     Get file status
161* @code{FTELL}:         FTELL,     Current stream position
162* @code{GAMMA}:         GAMMA,     Gamma function
163* @code{GERROR}:        GERROR,    Get last system error message
164* @code{GETARG}:        GETARG,    Get command line arguments
165* @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
166* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
167* @code{GETCWD}:        GETCWD,    Get current working directory
168* @code{GETENV}:        GETENV,    Get an environmental variable
169* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
170* @code{GETGID}:        GETGID,    Group ID function
171* @code{GETLOG}:        GETLOG,    Get login name
172* @code{GETPID}:        GETPID,    Process ID function
173* @code{GETUID}:        GETUID,    User ID function
174* @code{GMTIME}:        GMTIME,    Convert time to GMT info
175* @code{HOSTNM}:        HOSTNM,    Get system host name
176* @code{HUGE}:          HUGE,      Largest number of a kind
177* @code{HYPOT}:         HYPOT,     Euclidean distance function
178* @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
179* @code{IALL}:          IALL,      Bitwise AND of array elements
180* @code{IAND}:          IAND,      Bitwise logical and
181* @code{IANY}:          IANY,      Bitwise OR of array elements
182* @code{IARGC}:         IARGC,     Get the number of command line arguments
183* @code{IBCLR}:         IBCLR,     Clear bit
184* @code{IBITS}:         IBITS,     Bit extraction
185* @code{IBSET}:         IBSET,     Set bit
186* @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
187* @code{IDATE}:         IDATE,     Current local time (day/month/year)
188* @code{IEOR}:          IEOR,      Bitwise logical exclusive or
189* @code{IERRNO}:        IERRNO,    Function to get the last system error number
190* @code{IMAGE_INDEX}:   IMAGE_INDEX, Cosubscript to image index conversion
191* @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
192* @code{INT}:           INT,       Convert to integer type
193* @code{INT2}:          INT2,      Convert to 16-bit integer type
194* @code{INT8}:          INT8,      Convert to 64-bit integer type
195* @code{IOR}:           IOR,       Bitwise logical or
196* @code{IPARITY}:       IPARITY,   Bitwise XOR of array elements
197* @code{IRAND}:         IRAND,     Integer pseudo-random number
198* @code{IS_CONTIGUOUS}:  IS_CONTIGUOUS, Test whether an array is contiguous
199* @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
200* @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
201* @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
202* @code{ISHFT}:         ISHFT,     Shift bits
203* @code{ISHFTC}:        ISHFTC,    Shift bits circularly
204* @code{ISNAN}:         ISNAN,     Tests for a NaN
205* @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
206* @code{KILL}:          KILL,      Send a signal to a process
207* @code{KIND}:          KIND,      Kind of an entity
208* @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
209* @code{LCOBOUND}:      LCOBOUND,  Lower codimension bounds of an array
210* @code{LEADZ}:         LEADZ,     Number of leading zero bits of an integer
211* @code{LEN}:           LEN,       Length of a character entity
212* @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
213* @code{LGE}:           LGE,       Lexical greater than or equal
214* @code{LGT}:           LGT,       Lexical greater than
215* @code{LINK}:          LINK,      Create a hard link
216* @code{LLE}:           LLE,       Lexical less than or equal
217* @code{LLT}:           LLT,       Lexical less than
218* @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
219* @code{LOC}:           LOC,       Returns the address of a variable
220* @code{LOG}:           LOG,       Logarithm function
221* @code{LOG10}:         LOG10,     Base 10 logarithm function
222* @code{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
223* @code{LOGICAL}:       LOGICAL,   Convert to logical type
224* @code{LSHIFT}:        LSHIFT,    Left shift bits
225* @code{LSTAT}:         LSTAT,     Get file status
226* @code{LTIME}:         LTIME,     Convert time to local time info
227* @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
228* @code{MASKL}:         MASKL,     Left justified mask
229* @code{MASKR}:         MASKR,     Right justified mask
230* @code{MATMUL}:        MATMUL,    matrix multiplication
231* @code{MAX}:           MAX,       Maximum value of an argument list
232* @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
233* @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
234* @code{MAXVAL}:        MAXVAL,    Maximum value of an array
235* @code{MCLOCK}:        MCLOCK,    Time function
236* @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
237* @code{MERGE}:         MERGE,     Merge arrays
238* @code{MERGE_BITS}:    MERGE_BITS, Merge of bits under mask
239* @code{MIN}:           MIN,       Minimum value of an argument list
240* @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
241* @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
242* @code{MINVAL}:        MINVAL,    Minimum value of an array
243* @code{MOD}:           MOD,       Remainder function
244* @code{MODULO}:        MODULO,    Modulo function
245* @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
246* @code{MVBITS}:        MVBITS,    Move bits from one integer to another
247* @code{NEAREST}:       NEAREST,   Nearest representable number
248* @code{NEW_LINE}:      NEW_LINE,  New line character
249* @code{NINT}:          NINT,      Nearest whole number
250* @code{NORM2}:         NORM2,     Euclidean vector norm
251* @code{NOT}:           NOT,       Logical negation
252* @code{NULL}:          NULL,      Function that returns an disassociated pointer
253* @code{NUM_IMAGES}:    NUM_IMAGES, Number of images
254* @code{OR}:            OR,        Bitwise logical OR
255* @code{PACK}:          PACK,      Pack an array into an array of rank one
256* @code{PARITY}:        PARITY,    Reduction with exclusive OR
257* @code{PERROR}:        PERROR,    Print system error message
258* @code{POPCNT}:        POPCNT,    Number of bits set
259* @code{POPPAR}:        POPPAR,    Parity of the number of bits set
260* @code{PRECISION}:     PRECISION, Decimal precision of a real kind
261* @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
262* @code{PRODUCT}:       PRODUCT,   Product of array elements
263* @code{RADIX}:         RADIX,     Base of a data model
264* @code{RAN}:           RAN,       Real pseudo-random number
265* @code{RAND}:          RAND,      Real pseudo-random number
266* @code{RANDOM_INIT}:   RANDOM_INIT, Initialize pseudo-random number generator
267* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
268* @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
269* @code{RANGE}:         RANGE,     Decimal exponent range
270* @code{RANK} :         RANK,      Rank of a data object
271* @code{REAL}:          REAL,      Convert to real type
272* @code{RENAME}:        RENAME,    Rename a file
273* @code{REPEAT}:        REPEAT,    Repeated string concatenation
274* @code{RESHAPE}:       RESHAPE,   Function to reshape an array
275* @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
276* @code{RSHIFT}:        RSHIFT,    Right shift bits
277* @code{SAME_TYPE_AS}:  SAME_TYPE_AS,  Query dynamic types for equality
278* @code{SCALE}:         SCALE,     Scale a real value
279* @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
280* @code{SECNDS}:        SECNDS,    Time function
281* @code{SECOND}:        SECOND,    CPU time function
282* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
283* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
284* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
285* @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
286* @code{SHAPE}:         SHAPE,     Determine the shape of an array
287* @code{SHIFTA}:        SHIFTA,    Right shift with fill
288* @code{SHIFTL}:        SHIFTL,    Left shift
289* @code{SHIFTR}:        SHIFTR,    Right shift
290* @code{SIGN}:          SIGN,      Sign copying function
291* @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
292* @code{SIN}:           SIN,       Sine function
293* @code{SIND}:          SIND,      Sine function, degrees
294* @code{SINH}:          SINH,      Hyperbolic sine function
295* @code{SIZE}:          SIZE,      Function to determine the size of an array
296* @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
297* @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
298* @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
299* @code{SPREAD}:        SPREAD,    Add a dimension to an array
300* @code{SQRT}:          SQRT,      Square-root function
301* @code{SRAND}:         SRAND,     Reinitialize the random number generator
302* @code{STAT}:          STAT,      Get file status
303* @code{STORAGE_SIZE}:  STORAGE_SIZE, Storage size in bits
304* @code{SUM}:           SUM,       Sum of array elements
305* @code{SYMLNK}:        SYMLNK,    Create a symbolic link
306* @code{SYSTEM}:        SYSTEM,    Execute a shell command
307* @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
308* @code{TAN}:           TAN,       Tangent function
309* @code{TAND}:          TAND,      Tangent function, degrees
310* @code{TANH}:          TANH,      Hyperbolic tangent function
311* @code{THIS_IMAGE}:    THIS_IMAGE, Cosubscript index of this image
312* @code{TIME}:          TIME,      Time function
313* @code{TIME8}:         TIME8,     Time function (64-bit)
314* @code{TINY}:          TINY,      Smallest positive number of a real kind
315* @code{TRAILZ}:        TRAILZ,    Number of trailing zero bits of an integer
316* @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
317* @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
318* @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
319* @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
320* @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
321* @code{UCOBOUND}:      UCOBOUND,  Upper codimension bounds of an array
322* @code{UMASK}:         UMASK,     Set the file creation mask
323* @code{UNLINK}:        UNLINK,    Remove a file from the file system
324* @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
325* @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
326* @code{XOR}:           XOR,       Bitwise logical exclusive or
327@end menu
328
329@node Introduction to Intrinsics
330@section Introduction to intrinsic procedures
331
332The intrinsic procedures provided by GNU Fortran include procedures required
333by the Fortran 95 and later supported standards, and a set of intrinsic
334procedures for backwards compatibility with G77.  Any conflict between
335a description here and a description in the Fortran standards is
336unintentional, and the standard(s) should be considered authoritative.
337
338The enumeration of the @code{KIND} type parameter is processor defined in
339the Fortran 95 standard.  GNU Fortran defines the default integer type and
340default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
341respectively.  The standard mandates that both data types shall have
342another kind, which have more precision.  On typical target architectures
343supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
344Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
345In the description of generic intrinsic procedures, the kind type parameter
346will be specified by @code{KIND=*}, and in the description of specific
347names for an intrinsic procedure the kind type parameter will be explicitly
348given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
349brevity the optional @code{KIND=} syntax will be omitted.
350
351Many of the intrinsic procedures take one or more optional arguments.
352This document follows the convention used in the Fortran 95 standard,
353and denotes such arguments by square brackets.
354
355GNU Fortran offers the @option{-std=} command-line option,
356which can be used to restrict the set of intrinsic procedures to a
357given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
358option, and so all intrinsic procedures described here are accepted.  There
359is one caveat.  For a select group of intrinsic procedures, @command{g77}
360implemented both a function and a subroutine.  Both classes
361have been implemented in @command{gfortran} for backwards compatibility
362with @command{g77}.  It is noted here that these functions and subroutines
363cannot be intermixed in a given subprogram.  In the descriptions that follow,
364the applicable standard for each intrinsic procedure is noted.
365
366
367
368@node ABORT
369@section @code{ABORT} --- Abort the program
370@fnindex ABORT
371@cindex program termination, with core dump
372@cindex terminate program, with core dump
373@cindex core, dump
374
375@table @asis
376@item @emph{Description}:
377@code{ABORT} causes immediate termination of the program.  On operating
378systems that support a core dump, @code{ABORT} will produce a core dump.
379It will also print a backtrace, unless @code{-fno-backtrace} is given.
380
381@item @emph{Standard}:
382GNU extension
383
384@item @emph{Class}:
385Subroutine
386
387@item @emph{Syntax}:
388@code{CALL ABORT}
389
390@item @emph{Return value}:
391Does not return.
392
393@item @emph{Example}:
394@smallexample
395program test_abort
396  integer :: i = 1, j = 2
397  if (i /= j) call abort
398end program test_abort
399@end smallexample
400
401@item @emph{See also}:
402@ref{EXIT}, @gol
403@ref{KILL}, @gol
404@ref{BACKTRACE}
405@end table
406
407
408
409@node ABS
410@section @code{ABS} --- Absolute value
411@fnindex ABS
412@fnindex CABS
413@fnindex DABS
414@fnindex IABS
415@fnindex ZABS
416@fnindex CDABS
417@fnindex BABS
418@fnindex IIABS
419@fnindex JIABS
420@fnindex KIABS
421@cindex absolute value
422
423@table @asis
424@item @emph{Description}:
425@code{ABS(A)} computes the absolute value of @code{A}.
426
427@item @emph{Standard}:
428Fortran 77 and later, has overloads that are GNU extensions
429
430@item @emph{Class}:
431Elemental function
432
433@item @emph{Syntax}:
434@code{RESULT = ABS(A)}
435
436@item @emph{Arguments}:
437@multitable @columnfractions .15 .70
438@item @var{A} @tab The type of the argument shall be an @code{INTEGER},
439@code{REAL}, or @code{COMPLEX}.
440@end multitable
441
442@item @emph{Return value}:
443The return value is of the same type and
444kind as the argument except the return value is @code{REAL} for a
445@code{COMPLEX} argument.
446
447@item @emph{Example}:
448@smallexample
449program test_abs
450  integer :: i = -1
451  real :: x = -1.e0
452  complex :: z = (-1.e0,0.e0)
453  i = abs(i)
454  x = abs(x)
455  x = abs(z)
456end program test_abs
457@end smallexample
458
459@item @emph{Specific names}:
460@multitable @columnfractions .20 .23 .20 .33
461@headitem Name            @tab Argument            @tab Return type       @tab Standard
462@item @code{ABS(A)}   @tab @code{REAL(4) A}    @tab @code{REAL(4)}    @tab Fortran 77 and later
463@item @code{CABS(A)}  @tab @code{COMPLEX(4) A} @tab @code{REAL(4)}    @tab Fortran 77 and later
464@item @code{DABS(A)}  @tab @code{REAL(8) A}    @tab @code{REAL(8)}    @tab Fortran 77 and later
465@item @code{IABS(A)}  @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
466@item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
467@item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
468@item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
469@item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
470@item @code{ZABS(A)}  @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
471@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
472@end multitable
473@end table
474
475
476
477@node ACCESS
478@section @code{ACCESS} --- Checks file access modes
479@fnindex ACCESS
480@cindex file system, access mode
481
482@table @asis
483@item @emph{Description}:
484@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
485exists, is readable, writable or executable. Except for the
486executable check, @code{ACCESS} can be replaced by
487Fortran 95's @code{INQUIRE}.
488
489@item @emph{Standard}:
490GNU extension
491
492@item @emph{Class}:
493Inquiry function
494
495@item @emph{Syntax}:
496@code{RESULT = ACCESS(NAME, MODE)}
497
498@item @emph{Arguments}:
499@multitable @columnfractions .15 .70
500@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
501file name. Trailing blank are ignored unless the character @code{achar(0)}
502is present, then all characters up to and excluding @code{achar(0)} are
503used as file name.
504@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
505file access mode, may be any concatenation of @code{"r"} (readable),
506@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
507for existence.
508@end multitable
509
510@item @emph{Return value}:
511Returns a scalar @code{INTEGER}, which is @code{0} if the file is
512accessible in the given mode; otherwise or if an invalid argument
513has been given for @code{MODE} the value @code{1} is returned.
514
515@item @emph{Example}:
516@smallexample
517program access_test
518  implicit none
519  character(len=*), parameter :: file  = 'test.dat'
520  character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
521  if(access(file,' ') == 0) print *, trim(file),' is exists'
522  if(access(file,'r') == 0) print *, trim(file),' is readable'
523  if(access(file,'w') == 0) print *, trim(file),' is writable'
524  if(access(file,'x') == 0) print *, trim(file),' is executable'
525  if(access(file2,'rwx') == 0) &
526    print *, trim(file2),' is readable, writable and executable'
527end program access_test
528@end smallexample
529@end table
530
531
532
533@node ACHAR
534@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
535@fnindex ACHAR
536@cindex @acronym{ASCII} collating sequence
537@cindex collating sequence, @acronym{ASCII}
538
539@table @asis
540@item @emph{Description}:
541@code{ACHAR(I)} returns the character located at position @code{I}
542in the @acronym{ASCII} collating sequence.
543
544@item @emph{Standard}:
545Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
546
547@item @emph{Class}:
548Elemental function
549
550@item @emph{Syntax}:
551@code{RESULT = ACHAR(I [, KIND])}
552
553@item @emph{Arguments}:
554@multitable @columnfractions .15 .70
555@item @var{I}    @tab The type shall be @code{INTEGER}.
556@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
557expression indicating the kind parameter of the result.
558@end multitable
559
560@item @emph{Return value}:
561The return value is of type @code{CHARACTER} with a length of one.
562If the @var{KIND} argument is present, the return value is of the
563specified kind and of the default kind otherwise.
564
565@item @emph{Example}:
566@smallexample
567program test_achar
568  character c
569  c = achar(32)
570end program test_achar
571@end smallexample
572
573@item @emph{Note}:
574See @ref{ICHAR} for a discussion of converting between numerical values
575and formatted string representations.
576
577@item @emph{See also}:
578@ref{CHAR}, @gol
579@ref{IACHAR}, @gol
580@ref{ICHAR}
581@end table
582
583
584
585@node ACOS
586@section @code{ACOS} --- Arccosine function
587@fnindex ACOS
588@fnindex DACOS
589@cindex trigonometric function, cosine, inverse
590@cindex cosine, inverse
591
592@table @asis
593@item @emph{Description}:
594@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
595
596@item @emph{Standard}:
597Fortran 77 and later, for a complex argument Fortran 2008 or later
598
599@item @emph{Class}:
600Elemental function
601
602@item @emph{Syntax}:
603@code{RESULT = ACOS(X)}
604
605@item @emph{Arguments}:
606@multitable @columnfractions .15 .70
607@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
608less than or equal to one - or the type shall be @code{COMPLEX}.
609@end multitable
610
611@item @emph{Return value}:
612The return value is of the same type and kind as @var{X}.
613The real part of the result is in radians and lies in the range
614@math{0 \leq \Re \acos(x) \leq \pi}.
615
616@item @emph{Example}:
617@smallexample
618program test_acos
619  real(8) :: x = 0.866_8
620  x = acos(x)
621end program test_acos
622@end smallexample
623
624@item @emph{Specific names}:
625@multitable @columnfractions .20 .23 .20 .33
626@headitem Name            @tab Argument         @tab Return type     @tab Standard
627@item @code{ACOS(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}  @tab Fortran 77 and later
628@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}  @tab Fortran 77 and later
629@end multitable
630
631@item @emph{See also}:
632Inverse function: @gol
633@ref{COS} @gol
634Degrees function: @gol
635@ref{ACOSD}
636@end table
637
638
639
640@node ACOSD
641@section @code{ACOSD} --- Arccosine function, degrees
642@fnindex ACOSD
643@fnindex DACOSD
644@cindex trigonometric function, cosine, inverse, degrees
645@cindex cosine, inverse, degrees
646
647@table @asis
648@item @emph{Description}:
649@code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
650@code{COSD(X)}).
651
652This function is for compatibility only and should be avoided in favor of
653standard constructs wherever possible.
654
655@item @emph{Standard}:
656GNU extension, enabled with @option{-fdec-math}
657
658@item @emph{Class}:
659Elemental function
660
661@item @emph{Syntax}:
662@code{RESULT = ACOSD(X)}
663
664@item @emph{Arguments}:
665@multitable @columnfractions .15 .70
666@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
667less than or equal to one - or the type shall be @code{COMPLEX}.
668@end multitable
669
670@item @emph{Return value}:
671The return value is of the same type and kind as @var{X}.
672The real part of the result is in degrees and lies in the range
673@math{0 \leq \Re \acos(x) \leq 180}.
674
675@item @emph{Example}:
676@smallexample
677program test_acosd
678  real(8) :: x = 0.866_8
679  x = acosd(x)
680end program test_acosd
681@end smallexample
682
683@item @emph{Specific names}:
684@multitable @columnfractions .20 .23 .20 .33
685@headitem Name            @tab Argument         @tab Return type     @tab Standard
686@item @code{ACOSD(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}  @tab GNU extension
687@item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}  @tab GNU extension
688@end multitable
689
690@item @emph{See also}:
691Inverse function: @gol
692@ref{COSD} @gol
693Radians function: @gol
694@ref{ACOS} @gol
695@end table
696
697
698
699@node ACOSH
700@section @code{ACOSH} --- Inverse hyperbolic cosine function
701@fnindex ACOSH
702@fnindex DACOSH
703@cindex area hyperbolic cosine
704@cindex inverse hyperbolic cosine
705@cindex hyperbolic function, cosine, inverse
706@cindex cosine, hyperbolic, inverse
707
708@table @asis
709@item @emph{Description}:
710@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
711
712@item @emph{Standard}:
713Fortran 2008 and later
714
715@item @emph{Class}:
716Elemental function
717
718@item @emph{Syntax}:
719@code{RESULT = ACOSH(X)}
720
721@item @emph{Arguments}:
722@multitable @columnfractions .15 .70
723@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
724@end multitable
725
726@item @emph{Return value}:
727The return value has the same type and kind as @var{X}. If @var{X} is
728complex, the imaginary part of the result is in radians and lies between
729@math{ 0 \leq \Im \acosh(x) \leq \pi}.
730
731@item @emph{Example}:
732@smallexample
733PROGRAM test_acosh
734  REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
735  WRITE (*,*) ACOSH(x)
736END PROGRAM
737@end smallexample
738
739@item @emph{Specific names}:
740@multitable @columnfractions .20 .23 .20 .33
741@headitem Name             @tab Argument          @tab Return type       @tab Standard
742@item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
743@end multitable
744
745@item @emph{See also}:
746Inverse function: @gol
747@ref{COSH}
748@end table
749
750
751
752@node ADJUSTL
753@section @code{ADJUSTL} --- Left adjust a string
754@fnindex ADJUSTL
755@cindex string, adjust left
756@cindex adjust string
757
758@table @asis
759@item @emph{Description}:
760@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
761Spaces are inserted at the end of the string as needed.
762
763@item @emph{Standard}:
764Fortran 90 and later
765
766@item @emph{Class}:
767Elemental function
768
769@item @emph{Syntax}:
770@code{RESULT = ADJUSTL(STRING)}
771
772@item @emph{Arguments}:
773@multitable @columnfractions .15 .70
774@item @var{STRING} @tab The type shall be @code{CHARACTER}.
775@end multitable
776
777@item @emph{Return value}:
778The return value is of type @code{CHARACTER} and of the same kind as
779@var{STRING} where leading spaces are removed and the same number of
780spaces are inserted on the end of @var{STRING}.
781
782@item @emph{Example}:
783@smallexample
784program test_adjustl
785  character(len=20) :: str = '   gfortran'
786  str = adjustl(str)
787  print *, str
788end program test_adjustl
789@end smallexample
790
791@item @emph{See also}:
792@ref{ADJUSTR}, @gol
793@ref{TRIM}
794@end table
795
796
797
798@node ADJUSTR
799@section @code{ADJUSTR} --- Right adjust a string
800@fnindex ADJUSTR
801@cindex string, adjust right
802@cindex adjust string
803
804@table @asis
805@item @emph{Description}:
806@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
807Spaces are inserted at the start of the string as needed.
808
809@item @emph{Standard}:
810Fortran 90 and later
811
812@item @emph{Class}:
813Elemental function
814
815@item @emph{Syntax}:
816@code{RESULT = ADJUSTR(STRING)}
817
818@item @emph{Arguments}:
819@multitable @columnfractions .15 .70
820@item @var{STR} @tab The type shall be @code{CHARACTER}.
821@end multitable
822
823@item @emph{Return value}:
824The return value is of type @code{CHARACTER} and of the same kind as
825@var{STRING} where trailing spaces are removed and the same number of
826spaces are inserted at the start of @var{STRING}.
827
828@item @emph{Example}:
829@smallexample
830program test_adjustr
831  character(len=20) :: str = 'gfortran'
832  str = adjustr(str)
833  print *, str
834end program test_adjustr
835@end smallexample
836
837@item @emph{See also}:
838@ref{ADJUSTL}, @gol
839@ref{TRIM}
840@end table
841
842
843
844@node AIMAG
845@section @code{AIMAG} --- Imaginary part of complex number
846@fnindex AIMAG
847@fnindex DIMAG
848@fnindex IMAG
849@fnindex IMAGPART
850@cindex complex numbers, imaginary part
851
852@table @asis
853@item @emph{Description}:
854@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
855The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
856for compatibility with @command{g77}, and their use in new code is
857strongly discouraged.
858
859@item @emph{Standard}:
860Fortran 77 and later, has overloads that are GNU extensions
861
862@item @emph{Class}:
863Elemental function
864
865@item @emph{Syntax}:
866@code{RESULT = AIMAG(Z)}
867
868@item @emph{Arguments}:
869@multitable @columnfractions .15 .70
870@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
871@end multitable
872
873@item @emph{Return value}:
874The return value is of type @code{REAL} with the
875kind type parameter of the argument.
876
877@item @emph{Example}:
878@smallexample
879program test_aimag
880  complex(4) z4
881  complex(8) z8
882  z4 = cmplx(1.e0_4, 0.e0_4)
883  z8 = cmplx(0.e0_8, 1.e0_8)
884  print *, aimag(z4), dimag(z8)
885end program test_aimag
886@end smallexample
887
888@item @emph{Specific names}:
889@multitable @columnfractions .20 .23 .20 .33
890@headitem Name               @tab Argument            @tab Return type     @tab Standard
891@item @code{AIMAG(Z)}    @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab Fortran 77 and later
892@item @code{DIMAG(Z)}    @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}  @tab GNU extension
893@item @code{IMAG(Z)}     @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
894@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
895@end multitable
896@end table
897
898
899
900@node AINT
901@section @code{AINT} --- Truncate to a whole number
902@fnindex AINT
903@fnindex DINT
904@cindex floor
905@cindex rounding, floor
906
907@table @asis
908@item @emph{Description}:
909@code{AINT(A [, KIND])} truncates its argument to a whole number.
910
911@item @emph{Standard}:
912Fortran 77 and later
913
914@item @emph{Class}:
915Elemental function
916
917@item @emph{Syntax}:
918@code{RESULT = AINT(A [, KIND])}
919
920@item @emph{Arguments}:
921@multitable @columnfractions .15 .70
922@item @var{A}    @tab The type of the argument shall be @code{REAL}.
923@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
924expression indicating the kind parameter of the result.
925@end multitable
926
927@item @emph{Return value}:
928The return value is of type @code{REAL} with the kind type parameter of the
929argument if the optional @var{KIND} is absent; otherwise, the kind
930type parameter will be given by @var{KIND}.  If the magnitude of
931@var{X} is less than one, @code{AINT(X)} returns zero.  If the
932magnitude is equal to or greater than one then it returns the largest
933whole number that does not exceed its magnitude.  The sign is the same
934as the sign of @var{X}.
935
936@item @emph{Example}:
937@smallexample
938program test_aint
939  real(4) x4
940  real(8) x8
941  x4 = 1.234E0_4
942  x8 = 4.321_8
943  print *, aint(x4), dint(x8)
944  x8 = aint(x4,8)
945end program test_aint
946@end smallexample
947
948@item @emph{Specific names}:
949@multitable @columnfractions .20 .23 .20 .33
950@headitem Name           @tab Argument         @tab Return type      @tab Standard
951@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
952@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
953@end multitable
954@end table
955
956
957
958@node ALARM
959@section @code{ALARM} --- Execute a routine after a given delay
960@fnindex ALARM
961@cindex delayed execution
962
963@table @asis
964@item @emph{Description}:
965@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
966to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
967set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
968supplied, it will be returned with the number of seconds remaining until
969any previously scheduled alarm was due to be delivered, or zero if there
970was no previously scheduled alarm.
971
972@item @emph{Standard}:
973GNU extension
974
975@item @emph{Class}:
976Subroutine
977
978@item @emph{Syntax}:
979@code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
980
981@item @emph{Arguments}:
982@multitable @columnfractions .15 .70
983@item @var{SECONDS} @tab The type of the argument shall be a scalar
984@code{INTEGER}. It is @code{INTENT(IN)}.
985@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
986@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
987values may be either @code{SIG_IGN=1} to ignore the alarm generated
988or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
989@item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
990variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
991@end multitable
992
993@item @emph{Example}:
994@smallexample
995program test_alarm
996  external handler_print
997  integer i
998  call alarm (3, handler_print, i)
999  print *, i
1000  call sleep(10)
1001end program test_alarm
1002@end smallexample
1003This will cause the external routine @var{handler_print} to be called
1004after 3 seconds.
1005@end table
1006
1007
1008
1009@node ALL
1010@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
1011@fnindex ALL
1012@cindex array, apply condition
1013@cindex array, condition testing
1014
1015@table @asis
1016@item @emph{Description}:
1017@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
1018in the array along dimension @var{DIM}.
1019
1020@item @emph{Standard}:
1021Fortran 90 and later
1022
1023@item @emph{Class}:
1024Transformational function
1025
1026@item @emph{Syntax}:
1027@code{RESULT = ALL(MASK [, DIM])}
1028
1029@item @emph{Arguments}:
1030@multitable @columnfractions .15 .70
1031@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1032it shall not be scalar.
1033@item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1034with a value that lies between one and the rank of @var{MASK}.
1035@end multitable
1036
1037@item @emph{Return value}:
1038@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
1039the kind type parameter is the same as the kind type parameter of
1040@var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
1041an array with the rank of @var{MASK} minus 1.  The shape is determined from
1042the shape of @var{MASK} where the @var{DIM} dimension is elided.
1043
1044@table @asis
1045@item (A)
1046@code{ALL(MASK)} is true if all elements of @var{MASK} are true.
1047It also is true if @var{MASK} has zero size; otherwise, it is false.
1048@item (B)
1049If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
1050to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
1051is determined by applying @code{ALL} to the array sections.
1052@end table
1053
1054@item @emph{Example}:
1055@smallexample
1056program test_all
1057  logical l
1058  l = all((/.true., .true., .true./))
1059  print *, l
1060  call section
1061  contains
1062    subroutine section
1063      integer a(2,3), b(2,3)
1064      a = 1
1065      b = 1
1066      b(2,2) = 2
1067      print *, all(a .eq. b, 1)
1068      print *, all(a .eq. b, 2)
1069    end subroutine section
1070end program test_all
1071@end smallexample
1072@end table
1073
1074
1075
1076@node ALLOCATED
1077@section @code{ALLOCATED} --- Status of an allocatable entity
1078@fnindex ALLOCATED
1079@cindex allocation, status
1080
1081@table @asis
1082@item @emph{Description}:
1083@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1084status of @var{ARRAY} and @var{SCALAR}, respectively.
1085
1086@item @emph{Standard}:
1087Fortran 90 and later.  Note, the @code{SCALAR=} keyword and allocatable
1088scalar entities are available in Fortran 2003 and later.
1089
1090@item @emph{Class}:
1091Inquiry function
1092
1093@item @emph{Syntax}:
1094@multitable @columnfractions .80
1095@item @code{RESULT = ALLOCATED(ARRAY)}
1096@item @code{RESULT = ALLOCATED(SCALAR)}
1097@end multitable
1098
1099@item @emph{Arguments}:
1100@multitable @columnfractions .15 .70
1101@item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
1102@item @var{SCALAR}   @tab The argument shall be an @code{ALLOCATABLE} scalar.
1103@end multitable
1104
1105@item @emph{Return value}:
1106The return value is a scalar @code{LOGICAL} with the default logical
1107kind type parameter.  If the argument is allocated, then the result is
1108@code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1109
1110@item @emph{Example}:
1111@smallexample
1112program test_allocated
1113  integer :: i = 4
1114  real(4), allocatable :: x(:)
1115  if (.not. allocated(x)) allocate(x(i))
1116end program test_allocated
1117@end smallexample
1118@end table
1119
1120
1121
1122@node AND
1123@section @code{AND} --- Bitwise logical AND
1124@fnindex AND
1125@cindex bitwise logical and
1126@cindex logical and, bitwise
1127
1128@table @asis
1129@item @emph{Description}:
1130Bitwise logical @code{AND}.
1131
1132This intrinsic routine is provided for backwards compatibility with
1133GNU Fortran 77.  For integer arguments, programmers should consider
1134the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1135
1136@item @emph{Standard}:
1137GNU extension
1138
1139@item @emph{Class}:
1140Function
1141
1142@item @emph{Syntax}:
1143@code{RESULT = AND(I, J)}
1144
1145@item @emph{Arguments}:
1146@multitable @columnfractions .15 .70
1147@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1148type or a scalar @code{LOGICAL} type or a boz-literal-constant.
1149@item @var{J} @tab The type shall be the same as the type of @var{I} or
1150a boz-literal-constant. @var{I} and @var{J} shall not both be
1151boz-literal-constants.  If either @var{I} or @var{J} is a
1152boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
1153@end multitable
1154
1155@item @emph{Return value}:
1156The return type is either a scalar @code{INTEGER} or a scalar
1157@code{LOGICAL}.  If the kind type parameters differ, then the
1158smaller kind type is implicitly converted to larger kind, and the
1159return has the larger kind.  A boz-literal-constant is
1160converted to an @code{INTEGER} with the kind type parameter of
1161the other argument as-if a call to @ref{INT} occurred.
1162
1163@item @emph{Example}:
1164@smallexample
1165PROGRAM test_and
1166  LOGICAL :: T = .TRUE., F = .FALSE.
1167  INTEGER :: a, b
1168  DATA a / Z'F' /, b / Z'3' /
1169
1170  WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1171  WRITE (*,*) AND(a, b)
1172END PROGRAM
1173@end smallexample
1174
1175@item @emph{See also}:
1176Fortran 95 elemental function: @gol
1177@ref{IAND}
1178@end table
1179
1180
1181
1182@node ANINT
1183@section @code{ANINT} --- Nearest whole number
1184@fnindex ANINT
1185@fnindex DNINT
1186@cindex ceiling
1187@cindex rounding, ceiling
1188
1189@table @asis
1190@item @emph{Description}:
1191@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1192
1193@item @emph{Standard}:
1194Fortran 77 and later
1195
1196@item @emph{Class}:
1197Elemental function
1198
1199@item @emph{Syntax}:
1200@code{RESULT = ANINT(A [, KIND])}
1201
1202@item @emph{Arguments}:
1203@multitable @columnfractions .15 .70
1204@item @var{A}    @tab The type of the argument shall be @code{REAL}.
1205@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1206expression indicating the kind parameter of the result.
1207@end multitable
1208
1209@item @emph{Return value}:
1210The return value is of type real with the kind type parameter of the
1211argument if the optional @var{KIND} is absent; otherwise, the kind
1212type parameter will be given by @var{KIND}.  If @var{A} is greater than
1213zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
1214less than or equal to zero then it returns @code{AINT(X-0.5)}.
1215
1216@item @emph{Example}:
1217@smallexample
1218program test_anint
1219  real(4) x4
1220  real(8) x8
1221  x4 = 1.234E0_4
1222  x8 = 4.321_8
1223  print *, anint(x4), dnint(x8)
1224  x8 = anint(x4,8)
1225end program test_anint
1226@end smallexample
1227
1228@item @emph{Specific names}:
1229@multitable @columnfractions .20 .23 .20 .33
1230@headitem Name            @tab Argument         @tab Return type      @tab Standard
1231@item @code{ANINT(A)}  @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
1232@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
1233@end multitable
1234@end table
1235
1236
1237
1238@node ANY
1239@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1240@fnindex ANY
1241@cindex array, apply condition
1242@cindex array, condition testing
1243
1244@table @asis
1245@item @emph{Description}:
1246@code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1247@var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1248
1249@item @emph{Standard}:
1250Fortran 90 and later
1251
1252@item @emph{Class}:
1253Transformational function
1254
1255@item @emph{Syntax}:
1256@code{RESULT = ANY(MASK [, DIM])}
1257
1258@item @emph{Arguments}:
1259@multitable @columnfractions .15 .70
1260@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1261it shall not be scalar.
1262@item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1263with a value that lies between one and the rank of @var{MASK}.
1264@end multitable
1265
1266@item @emph{Return value}:
1267@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1268the kind type parameter is the same as the kind type parameter of
1269@var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1270an array with the rank of @var{MASK} minus 1.  The shape is determined from
1271the shape of @var{MASK} where the @var{DIM} dimension is elided.
1272
1273@table @asis
1274@item (A)
1275@code{ANY(MASK)} is true if any element of @var{MASK} is true;
1276otherwise, it is false.  It also is false if @var{MASK} has zero size.
1277@item (B)
1278If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1279to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1280is determined by applying @code{ANY} to the array sections.
1281@end table
1282
1283@item @emph{Example}:
1284@smallexample
1285program test_any
1286  logical l
1287  l = any((/.true., .true., .true./))
1288  print *, l
1289  call section
1290  contains
1291    subroutine section
1292      integer a(2,3), b(2,3)
1293      a = 1
1294      b = 1
1295      b(2,2) = 2
1296      print *, any(a .eq. b, 1)
1297      print *, any(a .eq. b, 2)
1298    end subroutine section
1299end program test_any
1300@end smallexample
1301@end table
1302
1303
1304
1305@node ASIN
1306@section @code{ASIN} --- Arcsine function
1307@fnindex ASIN
1308@fnindex DASIN
1309@cindex trigonometric function, sine, inverse
1310@cindex sine, inverse
1311
1312@table @asis
1313@item @emph{Description}:
1314@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1315
1316@item @emph{Standard}:
1317Fortran 77 and later, for a complex argument Fortran 2008 or later
1318
1319@item @emph{Class}:
1320Elemental function
1321
1322@item @emph{Syntax}:
1323@code{RESULT = ASIN(X)}
1324
1325@item @emph{Arguments}:
1326@multitable @columnfractions .15 .70
1327@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1328less than or equal to one - or be @code{COMPLEX}.
1329@end multitable
1330
1331@item @emph{Return value}:
1332The return value is of the same type and kind as @var{X}.
1333The real part of the result is in radians and lies in the range
1334@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1335
1336@item @emph{Example}:
1337@smallexample
1338program test_asin
1339  real(8) :: x = 0.866_8
1340  x = asin(x)
1341end program test_asin
1342@end smallexample
1343
1344@item @emph{Specific names}:
1345@multitable @columnfractions .20 .23 .20 .33
1346@headitem Name            @tab Argument          @tab Return type       @tab Standard
1347@item @code{ASIN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1348@item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1349@end multitable
1350
1351@item @emph{See also}:
1352Inverse function: @gol
1353@ref{SIN} @gol
1354Degrees function: @gol
1355@ref{ASIND}
1356@end table
1357
1358
1359
1360@node ASIND
1361@section @code{ASIND} --- Arcsine function, degrees
1362@fnindex ASIND
1363@fnindex DASIND
1364@cindex trigonometric function, sine, inverse, degrees
1365@cindex sine, inverse, degrees
1366
1367@table @asis
1368@item @emph{Description}:
1369@code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1370@code{SIND(X)}).
1371
1372This function is for compatibility only and should be avoided in favor of
1373standard constructs wherever possible.
1374
1375@item @emph{Standard}:
1376GNU extension, enabled with @option{-fdec-math}.
1377
1378@item @emph{Class}:
1379Elemental function
1380
1381@item @emph{Syntax}:
1382@code{RESULT = ASIND(X)}
1383
1384@item @emph{Arguments}:
1385@multitable @columnfractions .15 .70
1386@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1387less than or equal to one - or be @code{COMPLEX}.
1388@end multitable
1389
1390@item @emph{Return value}:
1391The return value is of the same type and kind as @var{X}.
1392The real part of the result is in degrees and lies in the range
1393@math{-90 \leq \Re \asin(x) \leq 90}.
1394
1395@item @emph{Example}:
1396@smallexample
1397program test_asind
1398  real(8) :: x = 0.866_8
1399  x = asind(x)
1400end program test_asind
1401@end smallexample
1402
1403@item @emph{Specific names}:
1404@multitable @columnfractions .20 .23 .20 .33
1405@headitem Name            @tab Argument          @tab Return type       @tab Standard
1406@item @code{ASIND(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab GNU extension
1407@item @code{DASIND(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1408@end multitable
1409
1410@item @emph{See also}:
1411Inverse function: @gol
1412@ref{SIND} @gol
1413Radians function: @gol
1414@ref{ASIN}
1415@end table
1416
1417
1418
1419@node ASINH
1420@section @code{ASINH} --- Inverse hyperbolic sine function
1421@fnindex ASINH
1422@fnindex DASINH
1423@cindex area hyperbolic sine
1424@cindex inverse hyperbolic sine
1425@cindex hyperbolic function, sine, inverse
1426@cindex sine, hyperbolic, inverse
1427
1428@table @asis
1429@item @emph{Description}:
1430@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1431
1432@item @emph{Standard}:
1433Fortran 2008 and later
1434
1435@item @emph{Class}:
1436Elemental function
1437
1438@item @emph{Syntax}:
1439@code{RESULT = ASINH(X)}
1440
1441@item @emph{Arguments}:
1442@multitable @columnfractions .15 .70
1443@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1444@end multitable
1445
1446@item @emph{Return value}:
1447The return value is of the same type and kind as  @var{X}. If @var{X} is
1448complex, the imaginary part of the result is in radians and lies between
1449@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1450
1451@item @emph{Example}:
1452@smallexample
1453PROGRAM test_asinh
1454  REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1455  WRITE (*,*) ASINH(x)
1456END PROGRAM
1457@end smallexample
1458
1459@item @emph{Specific names}:
1460@multitable @columnfractions .20 .23 .20 .33
1461@headitem Name             @tab Argument          @tab Return type       @tab Standard
1462@item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1463@end multitable
1464
1465@item @emph{See also}:
1466Inverse function: @gol
1467@ref{SINH}
1468@end table
1469
1470
1471
1472@node ASSOCIATED
1473@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1474@fnindex ASSOCIATED
1475@cindex pointer, status
1476@cindex association status
1477
1478@table @asis
1479@item @emph{Description}:
1480@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1481@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1482
1483@item @emph{Standard}:
1484Fortran 90 and later
1485
1486@item @emph{Class}:
1487Inquiry function
1488
1489@item @emph{Syntax}:
1490@code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1491
1492@item @emph{Arguments}:
1493@multitable @columnfractions .15 .70
1494@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1495and it can be of any type.
1496@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1497a target.  It must have the same type, kind type parameter, and
1498array rank as @var{POINTER}.
1499@end multitable
1500The association status of neither @var{POINTER} nor @var{TARGET} shall be
1501undefined.
1502
1503@item @emph{Return value}:
1504@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1505There are several cases:
1506@table @asis
1507@item (A) When the optional @var{TARGET} is not present then
1508@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1509@item (B) If @var{TARGET} is present and a scalar target, the result is true if
1510@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
1511disassociated, the result is false.
1512@item (C) If @var{TARGET} is present and an array target, the result is true if
1513@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1514are arrays whose elements are not zero-sized storage sequences, and
1515@var{TARGET} and @var{POINTER} occupy the same storage units in array element
1516order.
1517As in case(B), the result is false, if @var{POINTER} is disassociated.
1518@item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1519if @var{TARGET} is associated with @var{POINTER}, the target associated with
1520@var{TARGET} are not zero-sized storage sequences and occupy the same storage
1521units.
1522The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1523@item (E) If @var{TARGET} is present and an array pointer, the result is true if
1524target associated with @var{POINTER} and the target associated with @var{TARGET}
1525have the same shape, are not zero-sized arrays, are arrays whose elements are
1526not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1527the same storage units in array element order.
1528The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1529@end table
1530
1531@item @emph{Example}:
1532@smallexample
1533program test_associated
1534   implicit none
1535   real, target  :: tgt(2) = (/1., 2./)
1536   real, pointer :: ptr(:)
1537   ptr => tgt
1538   if (associated(ptr)     .eqv. .false.) call abort
1539   if (associated(ptr,tgt) .eqv. .false.) call abort
1540end program test_associated
1541@end smallexample
1542
1543@item @emph{See also}:
1544@ref{NULL}
1545@end table
1546
1547
1548
1549@node ATAN
1550@section @code{ATAN} --- Arctangent function
1551@fnindex ATAN
1552@fnindex DATAN
1553@cindex trigonometric function, tangent, inverse
1554@cindex tangent, inverse
1555
1556@table @asis
1557@item @emph{Description}:
1558@code{ATAN(X)} computes the arctangent of @var{X}.
1559
1560@item @emph{Standard}:
1561Fortran 77 and later, for a complex argument and for two arguments
1562Fortran 2008 or later
1563
1564@item @emph{Class}:
1565Elemental function
1566
1567@item @emph{Syntax}:
1568@multitable @columnfractions .80
1569@item @code{RESULT = ATAN(X)}
1570@item @code{RESULT = ATAN(Y, X)}
1571@end multitable
1572
1573@item @emph{Arguments}:
1574@multitable @columnfractions .15 .70
1575@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1576if @var{Y} is present, @var{X} shall be REAL.
1577@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
1578@end multitable
1579
1580@item @emph{Return value}:
1581The return value is of the same type and kind as @var{X}.
1582If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1583Otherwise, it the arcus tangent of @var{X}, where the real part of
1584the result is in radians and lies in the range
1585@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1586
1587@item @emph{Example}:
1588@smallexample
1589program test_atan
1590  real(8) :: x = 2.866_8
1591  x = atan(x)
1592end program test_atan
1593@end smallexample
1594
1595@item @emph{Specific names}:
1596@multitable @columnfractions .20 .23 .20 .33
1597@headitem Name            @tab Argument          @tab Return type       @tab Standard
1598@item @code{ATAN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1599@item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1600@end multitable
1601
1602@item @emph{See also}:
1603Inverse function: @gol
1604@ref{TAN} @gol
1605Degrees function: @gol
1606@ref{ATAND}
1607@end table
1608
1609
1610
1611@node ATAND
1612@section @code{ATAND} --- Arctangent function, degrees
1613@fnindex ATAND
1614@fnindex DATAND
1615@cindex trigonometric function, tangent, inverse, degrees
1616@cindex tangent, inverse, degrees
1617
1618@table @asis
1619@item @emph{Description}:
1620@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1621@ref{TAND}).
1622
1623This function is for compatibility only and should be avoided in favor of
1624standard constructs wherever possible.
1625
1626@item @emph{Standard}:
1627GNU extension, enabled with @option{-fdec-math}.
1628
1629@item @emph{Class}:
1630Elemental function
1631
1632@item @emph{Syntax}:
1633@multitable @columnfractions .80
1634@item @code{RESULT = ATAND(X)}
1635@item @code{RESULT = ATAND(Y, X)}
1636@end multitable
1637
1638@item @emph{Arguments}:
1639@multitable @columnfractions .15 .70
1640@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1641if @var{Y} is present, @var{X} shall be REAL.
1642@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
1643@end multitable
1644
1645@item @emph{Return value}:
1646The return value is of the same type and kind as @var{X}.
1647If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1648Otherwise, it is the arcus tangent of @var{X}, where the real part of
1649the result is in degrees and lies in the range
1650@math{-90 \leq \Re \atand(x) \leq 90}.
1651
1652@item @emph{Example}:
1653@smallexample
1654program test_atand
1655  real(8) :: x = 2.866_8
1656  x = atand(x)
1657end program test_atand
1658@end smallexample
1659
1660@item @emph{Specific names}:
1661@multitable @columnfractions .23 .23 .20 .30
1662@headitem Name            @tab Argument          @tab Return type       @tab Standard
1663@item @code{ATAND(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab GNU extension
1664@item @code{DATAND(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1665@end multitable
1666
1667@item @emph{See also}:
1668Inverse function: @gol
1669@ref{TAND} @gol
1670Radians function: @gol
1671@ref{ATAN}
1672@end table
1673
1674
1675
1676@node ATAN2
1677@section @code{ATAN2} --- Arctangent function
1678@fnindex ATAN2
1679@fnindex DATAN2
1680@cindex trigonometric function, tangent, inverse
1681@cindex tangent, inverse
1682
1683@table @asis
1684@item @emph{Description}:
1685@code{ATAN2(Y, X)} computes the principal value of the argument
1686function of the complex number @math{X + i Y}.  This function can
1687be used to transform from Cartesian into polar coordinates and
1688allows to determine the angle in the correct quadrant.
1689
1690@item @emph{Standard}:
1691Fortran 77 and later
1692
1693@item @emph{Class}:
1694Elemental function
1695
1696@item @emph{Syntax}:
1697@code{RESULT = ATAN2(Y, X)}
1698
1699@item @emph{Arguments}:
1700@multitable @columnfractions .15 .70
1701@item @var{Y} @tab The type shall be @code{REAL}.
1702@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1703If @var{Y} is zero, then @var{X} must be nonzero.
1704@end multitable
1705
1706@item @emph{Return value}:
1707The return value has the same type and kind type parameter as @var{Y}. It
1708is the principal value of the complex number @math{X + i Y}.  If @var{X}
1709is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1710The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1711the return value is zero if @var{X} is strictly positive, @math{\pi} if
1712@var{X} is negative and @var{Y} is positive zero (or the processor does
1713not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1714@var{Y} is negative zero.  Finally, if @var{X} is zero, then the
1715magnitude of the result is @math{\pi/2}.
1716
1717@item @emph{Example}:
1718@smallexample
1719program test_atan2
1720  real(4) :: x = 1.e0_4, y = 0.5e0_4
1721  x = atan2(y,x)
1722end program test_atan2
1723@end smallexample
1724
1725@item @emph{Specific names}:
1726@multitable @columnfractions .22 .22 .20 .32
1727@headitem Name                @tab Argument            @tab Return type    @tab Standard
1728@item @code{ATAN2(X, Y)}  @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1729@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1730@end multitable
1731
1732@item @emph{See also}:
1733Alias: @gol
1734@ref{ATAN} @gol
1735Degrees function: @gol
1736@ref{ATAN2D}
1737@end table
1738
1739
1740
1741@node ATAN2D
1742@section @code{ATAN2D} --- Arctangent function, degrees
1743@fnindex ATAN2D
1744@fnindex DATAN2D
1745@cindex trigonometric function, tangent, inverse, degrees
1746@cindex tangent, inverse, degrees
1747
1748@table @asis
1749@item @emph{Description}:
1750@code{ATAN2D(Y, X)} computes the principal value of the argument
1751function of the complex number @math{X + i Y} in degrees.  This function can
1752be used to transform from Cartesian into polar coordinates and
1753allows to determine the angle in the correct quadrant.
1754
1755This function is for compatibility only and should be avoided in favor of
1756standard constructs wherever possible.
1757
1758@item @emph{Standard}:
1759GNU extension, enabled with @option{-fdec-math}.
1760
1761@item @emph{Class}:
1762Elemental function
1763
1764@item @emph{Syntax}:
1765@code{RESULT = ATAN2D(Y, X)}
1766
1767@item @emph{Arguments}:
1768@multitable @columnfractions .15 .70
1769@item @var{Y} @tab The type shall be @code{REAL}.
1770@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1771If @var{Y} is zero, then @var{X} must be nonzero.
1772@end multitable
1773
1774@item @emph{Return value}:
1775The return value has the same type and kind type parameter as @var{Y}. It
1776is the principal value of the complex number @math{X + i Y}.  If @var{X}
1777is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1778The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1779the return value is zero if @var{X} is strictly positive, @math{180} if
1780@var{X} is negative and @var{Y} is positive zero (or the processor does
1781not handle signed zeros), and @math{-180} if @var{X} is negative and
1782@var{Y} is negative zero.  Finally, if @var{X} is zero, then the
1783magnitude of the result is @math{90}.
1784
1785@item @emph{Example}:
1786@smallexample
1787program test_atan2d
1788  real(4) :: x = 1.e0_4, y = 0.5e0_4
1789  x = atan2d(y,x)
1790end program test_atan2d
1791@end smallexample
1792
1793@item @emph{Specific names}:
1794@multitable @columnfractions .23 .23 .20 .30
1795@headitem Name                @tab Argument            @tab Return type    @tab Standard
1796@item @code{ATAN2D(X, Y)}  @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU extension
1797@item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension
1798@end multitable
1799
1800@item @emph{See also}:
1801Alias: @gol
1802@ref{ATAND} @gol
1803Radians function: @gol
1804@ref{ATAN2}
1805@end table
1806
1807
1808
1809@node ATANH
1810@section @code{ATANH} --- Inverse hyperbolic tangent function
1811@fnindex ATANH
1812@fnindex DATANH
1813@cindex area hyperbolic tangent
1814@cindex inverse hyperbolic tangent
1815@cindex hyperbolic function, tangent, inverse
1816@cindex tangent, hyperbolic, inverse
1817
1818@table @asis
1819@item @emph{Description}:
1820@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1821
1822@item @emph{Standard}:
1823Fortran 2008 and later
1824
1825@item @emph{Class}:
1826Elemental function
1827
1828@item @emph{Syntax}:
1829@code{RESULT = ATANH(X)}
1830
1831@item @emph{Arguments}:
1832@multitable @columnfractions .15 .70
1833@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1834@end multitable
1835
1836@item @emph{Return value}:
1837The return value has same type and kind as @var{X}. If @var{X} is
1838complex, the imaginary part of the result is in radians and lies between
1839@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1840
1841@item @emph{Example}:
1842@smallexample
1843PROGRAM test_atanh
1844  REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1845  WRITE (*,*) ATANH(x)
1846END PROGRAM
1847@end smallexample
1848
1849@item @emph{Specific names}:
1850@multitable @columnfractions .20 .23 .20 .33
1851@headitem Name             @tab Argument          @tab Return type       @tab Standard
1852@item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1853@end multitable
1854
1855@item @emph{See also}:
1856Inverse function: @gol
1857@ref{TANH}
1858@end table
1859
1860
1861
1862@node ATOMIC_ADD
1863@section @code{ATOMIC_ADD} --- Atomic ADD operation
1864@fnindex ATOMIC_ADD
1865@cindex Atomic subroutine, add
1866
1867@table @asis
1868@item @emph{Description}:
1869@code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VALUE} to the
1870variable @var{ATOM}. When @var{STAT} is present and the invocation was
1871successful, it is assigned the value 0. If it is present and the invocation
1872has failed, it is assigned a positive value; in particular, for a coindexed
1873@var{ATOM}, if the remote image has stopped, it is assigned the value of
1874@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1875failed, the value @code{STAT_FAILED_IMAGE}.
1876
1877@item @emph{Standard}:
1878TS 18508 or later
1879
1880@item @emph{Class}:
1881Atomic subroutine
1882
1883@item @emph{Syntax}:
1884@code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1885
1886@item @emph{Arguments}:
1887@multitable @columnfractions .15 .70
1888@item @var{ATOM}   @tab Scalar coarray or coindexed variable of integer
1889type with @code{ATOMIC_INT_KIND} kind.
1890@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
1891is different, the value is converted to the kind of @var{ATOM}.
1892@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
1893@end multitable
1894
1895@item @emph{Example}:
1896@smallexample
1897program atomic
1898  use iso_fortran_env
1899  integer(atomic_int_kind) :: atom[*]
1900  call atomic_add (atom[1], this_image())
1901end program atomic
1902@end smallexample
1903
1904@item @emph{See also}:
1905@ref{ATOMIC_DEFINE}, @gol
1906@ref{ATOMIC_FETCH_ADD}, @gol
1907@ref{ISO_FORTRAN_ENV}, @gol
1908@ref{ATOMIC_AND}, @gol
1909@ref{ATOMIC_OR}, @gol
1910@ref{ATOMIC_XOR}
1911@end table
1912
1913
1914
1915
1916@node ATOMIC_AND
1917@section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1918@fnindex ATOMIC_AND
1919@cindex Atomic subroutine, AND
1920
1921@table @asis
1922@item @emph{Description}:
1923@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1924AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1925and the invocation was successful, it is assigned the value 0. If it is present
1926and the invocation has failed, it is assigned a positive value; in particular,
1927for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1928value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1929image has failed, the value @code{STAT_FAILED_IMAGE}.
1930
1931@item @emph{Standard}:
1932TS 18508 or later
1933
1934@item @emph{Class}:
1935Atomic subroutine
1936
1937@item @emph{Syntax}:
1938@code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1939
1940@item @emph{Arguments}:
1941@multitable @columnfractions .15 .70
1942@item @var{ATOM}   @tab Scalar coarray or coindexed variable of integer
1943type with @code{ATOMIC_INT_KIND} kind.
1944@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
1945is different, the value is converted to the kind of @var{ATOM}.
1946@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
1947@end multitable
1948
1949@item @emph{Example}:
1950@smallexample
1951program atomic
1952  use iso_fortran_env
1953  integer(atomic_int_kind) :: atom[*]
1954  call atomic_and (atom[1], int(b'10100011101'))
1955end program atomic
1956@end smallexample
1957
1958@item @emph{See also}:
1959@ref{ATOMIC_DEFINE}, @gol
1960@ref{ATOMIC_FETCH_AND}, @gol
1961@ref{ISO_FORTRAN_ENV}, @gol
1962@ref{ATOMIC_ADD}, @gol
1963@ref{ATOMIC_OR}, @gol
1964@ref{ATOMIC_XOR}
1965@end table
1966
1967
1968
1969@node ATOMIC_CAS
1970@section @code{ATOMIC_CAS} --- Atomic compare and swap
1971@fnindex ATOMIC_DEFINE
1972@cindex Atomic subroutine, compare and swap
1973
1974@table @asis
1975@item @emph{Description}:
1976@code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1977@var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1978of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1979that was used for the comparison.  When @var{STAT} is present and the invocation
1980was successful, it is assigned the value 0. If it is present and the invocation
1981has failed, it is assigned a positive value; in particular, for a coindexed
1982@var{ATOM}, if the remote image has stopped, it is assigned the value of
1983@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1984failed, the value @code{STAT_FAILED_IMAGE}.
1985
1986@item @emph{Standard}:
1987TS 18508 or later
1988
1989@item @emph{Class}:
1990Atomic subroutine
1991
1992@item @emph{Syntax}:
1993@code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1994
1995@item @emph{Arguments}:
1996@multitable @columnfractions .15 .70
1997@item @var{ATOM}    @tab Scalar coarray or coindexed variable of either integer
1998type with @code{ATOMIC_INT_KIND} kind or logical type with
1999@code{ATOMIC_LOGICAL_KIND} kind.
2000@item @var{OLD}     @tab Scalar of the same type and kind as @var{ATOM}.
2001@item @var{COMPARE} @tab Scalar variable of the same type and kind as
2002@var{ATOM}.
2003@item @var{NEW}     @tab Scalar variable of the same type as @var{ATOM}. If kind
2004is different, the value is converted to the kind of @var{ATOM}.
2005@item @var{STAT}    @tab (optional) Scalar default-kind integer variable.
2006@end multitable
2007
2008@item @emph{Example}:
2009@smallexample
2010program atomic
2011  use iso_fortran_env
2012  logical(atomic_logical_kind) :: atom[*], prev
2013  call atomic_cas (atom[1], prev, .false., .true.))
2014end program atomic
2015@end smallexample
2016
2017@item @emph{See also}:
2018@ref{ATOMIC_DEFINE}, @gol
2019@ref{ATOMIC_REF}, @gol
2020@ref{ISO_FORTRAN_ENV}
2021@end table
2022
2023
2024
2025@node ATOMIC_DEFINE
2026@section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2027@fnindex ATOMIC_DEFINE
2028@cindex Atomic subroutine, define
2029
2030@table @asis
2031@item @emph{Description}:
2032@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2033@var{VALUE} atomically. When @var{STAT} is present and the invocation was
2034successful, it is assigned the value 0. If it is present and the invocation
2035has failed, it is assigned a positive value; in particular, for a coindexed
2036@var{ATOM}, if the remote image has stopped, it is assigned the value of
2037@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2038failed, the value @code{STAT_FAILED_IMAGE}.
2039
2040@item @emph{Standard}:
2041Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2042
2043@item @emph{Class}:
2044Atomic subroutine
2045
2046@item @emph{Syntax}:
2047@code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2048
2049@item @emph{Arguments}:
2050@multitable @columnfractions .15 .70
2051@item @var{ATOM}   @tab Scalar coarray or coindexed variable of either integer
2052type with @code{ATOMIC_INT_KIND} kind or logical type with
2053@code{ATOMIC_LOGICAL_KIND} kind.
2054
2055@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
2056is different, the value is converted to the kind of @var{ATOM}.
2057@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
2058@end multitable
2059
2060@item @emph{Example}:
2061@smallexample
2062program atomic
2063  use iso_fortran_env
2064  integer(atomic_int_kind) :: atom[*]
2065  call atomic_define (atom[1], this_image())
2066end program atomic
2067@end smallexample
2068
2069@item @emph{See also}:
2070@ref{ATOMIC_REF}, @gol
2071@ref{ATOMIC_CAS}, @gol
2072@ref{ISO_FORTRAN_ENV}, @gol
2073@ref{ATOMIC_ADD}, @gol
2074@ref{ATOMIC_AND}, @gol
2075@ref{ATOMIC_OR}, @gol
2076@ref{ATOMIC_XOR}
2077@end table
2078
2079
2080
2081@node ATOMIC_FETCH_ADD
2082@section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2083@fnindex ATOMIC_FETCH_ADD
2084@cindex Atomic subroutine, ADD with fetch
2085
2086@table @asis
2087@item @emph{Description}:
2088@code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2089@var{ATOM} in @var{OLD} and adds the value of @var{VALUE} to the
2090variable @var{ATOM}. When @var{STAT} is present and the invocation was
2091successful, it is assigned the value 0. If it is present and the invocation
2092has failed, it is assigned a positive value; in particular, for a coindexed
2093@var{ATOM}, if the remote image has stopped, it is assigned the value of
2094@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2095failed, the value @code{STAT_FAILED_IMAGE}.
2096
2097@item @emph{Standard}:
2098TS 18508 or later
2099
2100@item @emph{Class}:
2101Atomic subroutine
2102
2103@item @emph{Syntax}:
2104@code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2105
2106@item @emph{Arguments}:
2107@multitable @columnfractions .15 .70
2108@item @var{ATOM}   @tab Scalar coarray or coindexed variable of integer
2109type with @code{ATOMIC_INT_KIND} kind.
2110@code{ATOMIC_LOGICAL_KIND} kind.
2111
2112@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
2113is different, the value is converted to the kind of @var{ATOM}.
2114@item @var{OLD}    @tab Scalar of the same type and kind as @var{ATOM}.
2115@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
2116@end multitable
2117
2118@item @emph{Example}:
2119@smallexample
2120program atomic
2121  use iso_fortran_env
2122  integer(atomic_int_kind) :: atom[*], old
2123  call atomic_add (atom[1], this_image(), old)
2124end program atomic
2125@end smallexample
2126
2127@item @emph{See also}:
2128@ref{ATOMIC_DEFINE}, @gol
2129@ref{ATOMIC_ADD}, @gol
2130@ref{ISO_FORTRAN_ENV}, @gol
2131@ref{ATOMIC_FETCH_AND}, @gol
2132@ref{ATOMIC_FETCH_OR}, @gol
2133@ref{ATOMIC_FETCH_XOR}
2134@end table
2135
2136
2137
2138@node ATOMIC_FETCH_AND
2139@section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2140@fnindex ATOMIC_FETCH_AND
2141@cindex Atomic subroutine, AND with fetch
2142
2143@table @asis
2144@item @emph{Description}:
2145@code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2146@var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2147@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2148successful, it is assigned the value 0. If it is present and the invocation has
2149failed, it is assigned a positive value; in particular, for a coindexed
2150@var{ATOM}, if the remote image has stopped, it is assigned the value of
2151@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2152failed, the value @code{STAT_FAILED_IMAGE}.
2153
2154@item @emph{Standard}:
2155TS 18508 or later
2156
2157@item @emph{Class}:
2158Atomic subroutine
2159
2160@item @emph{Syntax}:
2161@code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2162
2163@item @emph{Arguments}:
2164@multitable @columnfractions .15 .70
2165@item @var{ATOM}   @tab Scalar coarray or coindexed variable of integer
2166type with @code{ATOMIC_INT_KIND} kind.
2167@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
2168is different, the value is converted to the kind of @var{ATOM}.
2169@item @var{OLD}    @tab Scalar of the same type and kind as @var{ATOM}.
2170@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
2171@end multitable
2172
2173@item @emph{Example}:
2174@smallexample
2175program atomic
2176  use iso_fortran_env
2177  integer(atomic_int_kind) :: atom[*], old
2178  call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2179end program atomic
2180@end smallexample
2181
2182@item @emph{See also}:
2183@ref{ATOMIC_DEFINE}, @gol
2184@ref{ATOMIC_AND}, @gol
2185@ref{ISO_FORTRAN_ENV}, @gol
2186@ref{ATOMIC_FETCH_ADD}, @gol
2187@ref{ATOMIC_FETCH_OR}, @gol
2188@ref{ATOMIC_FETCH_XOR}
2189@end table
2190
2191
2192
2193@node ATOMIC_FETCH_OR
2194@section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2195@fnindex ATOMIC_FETCH_OR
2196@cindex Atomic subroutine, OR with fetch
2197
2198@table @asis
2199@item @emph{Description}:
2200@code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2201@var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2202@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2203successful, it is assigned the value 0. If it is present and the invocation has
2204failed, it is assigned a positive value; in particular, for a coindexed
2205@var{ATOM}, if the remote image has stopped, it is assigned the value of
2206@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2207failed, the value @code{STAT_FAILED_IMAGE}.
2208
2209@item @emph{Standard}:
2210TS 18508 or later
2211
2212@item @emph{Class}:
2213Atomic subroutine
2214
2215@item @emph{Syntax}:
2216@code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2217
2218@item @emph{Arguments}:
2219@multitable @columnfractions .15 .70
2220@item @var{ATOM}   @tab Scalar coarray or coindexed variable of integer
2221type with @code{ATOMIC_INT_KIND} kind.
2222@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
2223is different, the value is converted to the kind of @var{ATOM}.
2224@item @var{OLD}    @tab Scalar of the same type and kind as @var{ATOM}.
2225@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
2226@end multitable
2227
2228@item @emph{Example}:
2229@smallexample
2230program atomic
2231  use iso_fortran_env
2232  integer(atomic_int_kind) :: atom[*], old
2233  call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2234end program atomic
2235@end smallexample
2236
2237@item @emph{See also}:
2238@ref{ATOMIC_DEFINE}, @gol
2239@ref{ATOMIC_OR}, @gol
2240@ref{ISO_FORTRAN_ENV}, @gol
2241@ref{ATOMIC_FETCH_ADD}, @gol
2242@ref{ATOMIC_FETCH_AND}, @gol
2243@ref{ATOMIC_FETCH_XOR}
2244@end table
2245
2246
2247
2248@node ATOMIC_FETCH_XOR
2249@section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2250@fnindex ATOMIC_FETCH_XOR
2251@cindex Atomic subroutine, XOR with fetch
2252
2253@table @asis
2254@item @emph{Description}:
2255@code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2256@var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2257@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2258successful, it is assigned the value 0. If it is present and the invocation has
2259failed, it is assigned a positive value; in particular, for a coindexed
2260@var{ATOM}, if the remote image has stopped, it is assigned the value of
2261@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2262failed, the value @code{STAT_FAILED_IMAGE}.
2263
2264@item @emph{Standard}:
2265TS 18508 or later
2266
2267@item @emph{Class}:
2268Atomic subroutine
2269
2270@item @emph{Syntax}:
2271@code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2272
2273@item @emph{Arguments}:
2274@multitable @columnfractions .15 .70
2275@item @var{ATOM}   @tab Scalar coarray or coindexed variable of integer
2276type with @code{ATOMIC_INT_KIND} kind.
2277@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
2278is different, the value is converted to the kind of @var{ATOM}.
2279@item @var{OLD}    @tab Scalar of the same type and kind as @var{ATOM}.
2280@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
2281@end multitable
2282
2283@item @emph{Example}:
2284@smallexample
2285program atomic
2286  use iso_fortran_env
2287  integer(atomic_int_kind) :: atom[*], old
2288  call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2289end program atomic
2290@end smallexample
2291
2292@item @emph{See also}:
2293@ref{ATOMIC_DEFINE}, @gol
2294@ref{ATOMIC_XOR}, @gol
2295@ref{ISO_FORTRAN_ENV}, @gol
2296@ref{ATOMIC_FETCH_ADD}, @gol
2297@ref{ATOMIC_FETCH_AND}, @gol
2298@ref{ATOMIC_FETCH_OR}
2299@end table
2300
2301
2302
2303@node ATOMIC_OR
2304@section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2305@fnindex ATOMIC_OR
2306@cindex Atomic subroutine, OR
2307
2308@table @asis
2309@item @emph{Description}:
2310@code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2311AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2312and the invocation was successful, it is assigned the value 0. If it is present
2313and the invocation has failed, it is assigned a positive value; in particular,
2314for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2315value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2316image has failed, the value @code{STAT_FAILED_IMAGE}.
2317
2318@item @emph{Standard}:
2319TS 18508 or later
2320
2321@item @emph{Class}:
2322Atomic subroutine
2323
2324@item @emph{Syntax}:
2325@code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2326
2327@item @emph{Arguments}:
2328@multitable @columnfractions .15 .70
2329@item @var{ATOM}   @tab Scalar coarray or coindexed variable of integer
2330type with @code{ATOMIC_INT_KIND} kind.
2331@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
2332is different, the value is converted to the kind of @var{ATOM}.
2333@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
2334@end multitable
2335
2336@item @emph{Example}:
2337@smallexample
2338program atomic
2339  use iso_fortran_env
2340  integer(atomic_int_kind) :: atom[*]
2341  call atomic_or (atom[1], int(b'10100011101'))
2342end program atomic
2343@end smallexample
2344
2345@item @emph{See also}:
2346@ref{ATOMIC_DEFINE}, @gol
2347@ref{ATOMIC_FETCH_OR}, @gol
2348@ref{ISO_FORTRAN_ENV}, @gol
2349@ref{ATOMIC_ADD}, @gol
2350@ref{ATOMIC_OR}, @gol
2351@ref{ATOMIC_XOR}
2352@end table
2353
2354
2355
2356@node ATOMIC_REF
2357@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2358@fnindex ATOMIC_REF
2359@cindex Atomic subroutine, reference
2360
2361@table @asis
2362@item @emph{Description}:
2363@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2364variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2365invocation was successful, it is assigned the value 0. If it is present and the
2366invocation has failed, it is assigned a positive value; in particular, for a
2367coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2368of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2369has failed, the value @code{STAT_FAILED_IMAGE}.
2370
2371
2372@item @emph{Standard}:
2373Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2374
2375@item @emph{Class}:
2376Atomic subroutine
2377
2378@item @emph{Syntax}:
2379@code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2380
2381@item @emph{Arguments}:
2382@multitable @columnfractions .15 .70
2383@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
2384is different, the value is converted to the kind of @var{ATOM}.
2385@item @var{ATOM}   @tab Scalar coarray or coindexed variable of either integer
2386type with @code{ATOMIC_INT_KIND} kind or logical type with
2387@code{ATOMIC_LOGICAL_KIND} kind.
2388@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
2389@end multitable
2390
2391@item @emph{Example}:
2392@smallexample
2393program atomic
2394  use iso_fortran_env
2395  logical(atomic_logical_kind) :: atom[*]
2396  logical :: val
2397  call atomic_ref (atom, .false.)
2398  ! ...
2399  call atomic_ref (atom, val)
2400  if (val) then
2401    print *, "Obtained"
2402  end if
2403end program atomic
2404@end smallexample
2405
2406@item @emph{See also}:
2407@ref{ATOMIC_DEFINE}, @gol
2408@ref{ATOMIC_CAS}, @gol
2409@ref{ISO_FORTRAN_ENV}, @gol
2410@ref{ATOMIC_FETCH_ADD}, @gol
2411@ref{ATOMIC_FETCH_AND}, @gol
2412@ref{ATOMIC_FETCH_OR}, @gol
2413@ref{ATOMIC_FETCH_XOR}
2414@end table
2415
2416
2417@node ATOMIC_XOR
2418@section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2419@fnindex ATOMIC_XOR
2420@cindex Atomic subroutine, XOR
2421
2422@table @asis
2423@item @emph{Description}:
2424@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2425XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2426and the invocation was successful, it is assigned the value 0. If it is present
2427and the invocation has failed, it is assigned a positive value; in particular,
2428for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2429value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2430image has failed, the value @code{STAT_FAILED_IMAGE}.
2431
2432@item @emph{Standard}:
2433TS 18508 or later
2434
2435@item @emph{Class}:
2436Atomic subroutine
2437
2438@item @emph{Syntax}:
2439@code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2440
2441@item @emph{Arguments}:
2442@multitable @columnfractions .15 .70
2443@item @var{ATOM}   @tab Scalar coarray or coindexed variable of integer
2444type with @code{ATOMIC_INT_KIND} kind.
2445@item @var{VALUE}  @tab Scalar of the same type as @var{ATOM}. If the kind
2446is different, the value is converted to the kind of @var{ATOM}.
2447@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
2448@end multitable
2449
2450@item @emph{Example}:
2451@smallexample
2452program atomic
2453  use iso_fortran_env
2454  integer(atomic_int_kind) :: atom[*]
2455  call atomic_xor (atom[1], int(b'10100011101'))
2456end program atomic
2457@end smallexample
2458
2459@item @emph{See also}:
2460@ref{ATOMIC_DEFINE}, @gol
2461@ref{ATOMIC_FETCH_XOR}, @gol
2462@ref{ISO_FORTRAN_ENV}, @gol
2463@ref{ATOMIC_ADD}, @gol
2464@ref{ATOMIC_OR}, @gol
2465@ref{ATOMIC_XOR}
2466@end table
2467
2468
2469@node BACKTRACE
2470@section @code{BACKTRACE} --- Show a backtrace
2471@fnindex BACKTRACE
2472@cindex backtrace
2473
2474@table @asis
2475@item @emph{Description}:
2476@code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2477execution continues normally afterwards. The backtrace information is printed
2478to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2479
2480@item @emph{Standard}:
2481GNU extension
2482
2483@item @emph{Class}:
2484Subroutine
2485
2486@item @emph{Syntax}:
2487@code{CALL BACKTRACE}
2488
2489@item @emph{Arguments}:
2490None
2491
2492@item @emph{See also}:
2493@ref{ABORT}
2494@end table
2495
2496
2497
2498@node BESSEL_J0
2499@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2500@fnindex BESSEL_J0
2501@fnindex BESJ0
2502@fnindex DBESJ0
2503@cindex Bessel function, first kind
2504
2505@table @asis
2506@item @emph{Description}:
2507@code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2508order 0 of @var{X}. This function is available under the name
2509@code{BESJ0} as a GNU extension.
2510
2511@item @emph{Standard}:
2512Fortran 2008 and later
2513
2514@item @emph{Class}:
2515Elemental function
2516
2517@item @emph{Syntax}:
2518@code{RESULT = BESSEL_J0(X)}
2519
2520@item @emph{Arguments}:
2521@multitable @columnfractions .15 .70
2522@item @var{X} @tab The type shall be @code{REAL}.
2523@end multitable
2524
2525@item @emph{Return value}:
2526The return value is of type @code{REAL} and lies in the
2527range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2528kind as @var{X}.
2529
2530@item @emph{Example}:
2531@smallexample
2532program test_besj0
2533  real(8) :: x = 0.0_8
2534  x = bessel_j0(x)
2535end program test_besj0
2536@end smallexample
2537
2538@item @emph{Specific names}:
2539@multitable @columnfractions .21 .22 .20 .33
2540@headitem Name            @tab Argument          @tab Return type       @tab Standard
2541@item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
2542@end multitable
2543@end table
2544
2545
2546
2547@node BESSEL_J1
2548@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2549@fnindex BESSEL_J1
2550@fnindex BESJ1
2551@fnindex DBESJ1
2552@cindex Bessel function, first kind
2553
2554@table @asis
2555@item @emph{Description}:
2556@code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2557order 1 of @var{X}. This function is available under the name
2558@code{BESJ1} as a GNU extension.
2559
2560@item @emph{Standard}:
2561Fortran 2008
2562
2563@item @emph{Class}:
2564Elemental function
2565
2566@item @emph{Syntax}:
2567@code{RESULT = BESSEL_J1(X)}
2568
2569@item @emph{Arguments}:
2570@multitable @columnfractions .15 .70
2571@item @var{X} @tab The type shall be @code{REAL}.
2572@end multitable
2573
2574@item @emph{Return value}:
2575The return value is of type @code{REAL} and lies in the
2576range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2577kind as @var{X}.
2578
2579@item @emph{Example}:
2580@smallexample
2581program test_besj1
2582  real(8) :: x = 1.0_8
2583  x = bessel_j1(x)
2584end program test_besj1
2585@end smallexample
2586
2587@item @emph{Specific names}:
2588@multitable @columnfractions .20 .23 .20 .33
2589@headitem Name             @tab Argument          @tab Return type       @tab Standard
2590@item @code{DBESJ1(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
2591@end multitable
2592@end table
2593
2594
2595
2596@node BESSEL_JN
2597@section @code{BESSEL_JN} --- Bessel function of the first kind
2598@fnindex BESSEL_JN
2599@fnindex BESJN
2600@fnindex DBESJN
2601@cindex Bessel function, first kind
2602
2603@table @asis
2604@item @emph{Description}:
2605@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2606order @var{N} of @var{X}. This function is available under the name
2607@code{BESJN} as a GNU extension.  If @var{N} and @var{X} are arrays,
2608their ranks and shapes shall conform.
2609
2610@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2611of the first kind of the orders @var{N1} to @var{N2}.
2612
2613@item @emph{Standard}:
2614Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2615
2616@item @emph{Class}:
2617Elemental function, except for the transformational function
2618@code{BESSEL_JN(N1, N2, X)}
2619
2620@item @emph{Syntax}:
2621@multitable @columnfractions .80
2622@item @code{RESULT = BESSEL_JN(N, X)}
2623@item @code{RESULT = BESSEL_JN(N1, N2, X)}
2624@end multitable
2625
2626@item @emph{Arguments}:
2627@multitable @columnfractions .15 .70
2628@item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
2629@item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
2630@item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
2631@item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
2632for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2633@end multitable
2634
2635@item @emph{Return value}:
2636The return value is a scalar of type @code{REAL}. It has the same
2637kind as @var{X}.
2638
2639@item @emph{Note}:
2640The transformational function uses a recurrence algorithm which might,
2641for some values of @var{X}, lead to different results than calls to
2642the elemental function.
2643
2644@item @emph{Example}:
2645@smallexample
2646program test_besjn
2647  real(8) :: x = 1.0_8
2648  x = bessel_jn(5,x)
2649end program test_besjn
2650@end smallexample
2651
2652@item @emph{Specific names}:
2653@multitable @columnfractions .22 .22 .20 .32
2654@headitem Name                @tab Argument            @tab Return type       @tab Standard
2655@item @code{DBESJN(N, X)} @tab @code{INTEGER N}    @tab @code{REAL(8)}    @tab GNU extension
2656@item                     @tab @code{REAL(8) X}    @tab                   @tab
2657@end multitable
2658@end table
2659
2660
2661
2662@node BESSEL_Y0
2663@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2664@fnindex BESSEL_Y0
2665@fnindex BESY0
2666@fnindex DBESY0
2667@cindex Bessel function, second kind
2668
2669@table @asis
2670@item @emph{Description}:
2671@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2672order 0 of @var{X}. This function is available under the name
2673@code{BESY0} as a GNU extension.
2674
2675@item @emph{Standard}:
2676Fortran 2008 and later
2677
2678@item @emph{Class}:
2679Elemental function
2680
2681@item @emph{Syntax}:
2682@code{RESULT = BESSEL_Y0(X)}
2683
2684@item @emph{Arguments}:
2685@multitable @columnfractions .15 .70
2686@item @var{X} @tab The type shall be @code{REAL}.
2687@end multitable
2688
2689@item @emph{Return value}:
2690The return value is of type @code{REAL}. It has the same kind as @var{X}.
2691
2692@item @emph{Example}:
2693@smallexample
2694program test_besy0
2695  real(8) :: x = 0.0_8
2696  x = bessel_y0(x)
2697end program test_besy0
2698@end smallexample
2699
2700@item @emph{Specific names}:
2701@multitable @columnfractions .20 .23 .20 .33
2702@headitem Name            @tab Argument          @tab Return type       @tab Standard
2703@item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
2704@end multitable
2705@end table
2706
2707
2708
2709@node BESSEL_Y1
2710@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2711@fnindex BESSEL_Y1
2712@fnindex BESY1
2713@fnindex DBESY1
2714@cindex Bessel function, second kind
2715
2716@table @asis
2717@item @emph{Description}:
2718@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2719order 1 of @var{X}. This function is available under the name
2720@code{BESY1} as a GNU extension.
2721
2722@item @emph{Standard}:
2723Fortran 2008 and later
2724
2725@item @emph{Class}:
2726Elemental function
2727
2728@item @emph{Syntax}:
2729@code{RESULT = BESSEL_Y1(X)}
2730
2731@item @emph{Arguments}:
2732@multitable @columnfractions .15 .70
2733@item @var{X} @tab The type shall be @code{REAL}.
2734@end multitable
2735
2736@item @emph{Return value}:
2737The return value is of type @code{REAL}. It has the same kind as @var{X}.
2738
2739@item @emph{Example}:
2740@smallexample
2741program test_besy1
2742  real(8) :: x = 1.0_8
2743  x = bessel_y1(x)
2744end program test_besy1
2745@end smallexample
2746
2747@item @emph{Specific names}:
2748@multitable @columnfractions .20 .23 .20 .33
2749@headitem Name            @tab Argument          @tab Return type       @tab Standard
2750@item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
2751@end multitable
2752@end table
2753
2754
2755
2756@node BESSEL_YN
2757@section @code{BESSEL_YN} --- Bessel function of the second kind
2758@fnindex BESSEL_YN
2759@fnindex BESYN
2760@fnindex DBESYN
2761@cindex Bessel function, second kind
2762
2763@table @asis
2764@item @emph{Description}:
2765@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2766order @var{N} of @var{X}. This function is available under the name
2767@code{BESYN} as a GNU extension.  If @var{N} and @var{X} are arrays,
2768their ranks and shapes shall conform.
2769
2770@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2771of the first kind of the orders @var{N1} to @var{N2}.
2772
2773@item @emph{Standard}:
2774Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2775
2776@item @emph{Class}:
2777Elemental function, except for the transformational function
2778@code{BESSEL_YN(N1, N2, X)}
2779
2780@item @emph{Syntax}:
2781@multitable @columnfractions .80
2782@item @code{RESULT = BESSEL_YN(N, X)}
2783@item @code{RESULT = BESSEL_YN(N1, N2, X)}
2784@end multitable
2785
2786@item @emph{Arguments}:
2787@multitable @columnfractions .15 .70
2788@item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER} .
2789@item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
2790@item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
2791@item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
2792for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2793@end multitable
2794
2795@item @emph{Return value}:
2796The return value is a scalar of type @code{REAL}. It has the same
2797kind as @var{X}.
2798
2799@item @emph{Note}:
2800The transformational function uses a recurrence algorithm which might,
2801for some values of @var{X}, lead to different results than calls to
2802the elemental function.
2803
2804@item @emph{Example}:
2805@smallexample
2806program test_besyn
2807  real(8) :: x = 1.0_8
2808  x = bessel_yn(5,x)
2809end program test_besyn
2810@end smallexample
2811
2812@item @emph{Specific names}:
2813@multitable @columnfractions .20 .23 .20 .33
2814@headitem Name               @tab Argument            @tab Return type     @tab Standard
2815@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
2816@item                    @tab @code{REAL(8) X} @tab                 @tab
2817@end multitable
2818@end table
2819
2820
2821
2822@node BGE
2823@section @code{BGE} --- Bitwise greater than or equal to
2824@fnindex BGE
2825@cindex bitwise comparison
2826
2827@table @asis
2828@item @emph{Description}:
2829Determines whether an integral is a bitwise greater than or equal to
2830another.
2831
2832@item @emph{Standard}:
2833Fortran 2008 and later
2834
2835@item @emph{Class}:
2836Elemental function
2837
2838@item @emph{Syntax}:
2839@code{RESULT = BGE(I, J)}
2840
2841@item @emph{Arguments}:
2842@multitable @columnfractions .15 .70
2843@item @var{I} @tab Shall be of @code{INTEGER} type.
2844@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2845as @var{I}.
2846@end multitable
2847
2848@item @emph{Return value}:
2849The return value is of type @code{LOGICAL} and of the default kind.
2850
2851@item @emph{See also}:
2852@ref{BGT}, @gol
2853@ref{BLE}, @gol
2854@ref{BLT}
2855@end table
2856
2857
2858
2859@node BGT
2860@section @code{BGT} --- Bitwise greater than
2861@fnindex BGT
2862@cindex bitwise comparison
2863
2864@table @asis
2865@item @emph{Description}:
2866Determines whether an integral is a bitwise greater than another.
2867
2868@item @emph{Standard}:
2869Fortran 2008 and later
2870
2871@item @emph{Class}:
2872Elemental function
2873
2874@item @emph{Syntax}:
2875@code{RESULT = BGT(I, J)}
2876
2877@item @emph{Arguments}:
2878@multitable @columnfractions .15 .70
2879@item @var{I} @tab Shall be of @code{INTEGER} type.
2880@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2881as @var{I}.
2882@end multitable
2883
2884@item @emph{Return value}:
2885The return value is of type @code{LOGICAL} and of the default kind.
2886
2887@item @emph{See also}:
2888@ref{BGE}, @gol
2889@ref{BLE}, @gol
2890@ref{BLT}
2891@end table
2892
2893
2894
2895@node BIT_SIZE
2896@section @code{BIT_SIZE} --- Bit size inquiry function
2897@fnindex BIT_SIZE
2898@cindex bits, number of
2899@cindex size of a variable, in bits
2900
2901@table @asis
2902@item @emph{Description}:
2903@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2904represented by the type of @var{I}.  The result of @code{BIT_SIZE(I)} is
2905independent of the actual value of @var{I}.
2906
2907@item @emph{Standard}:
2908Fortran 90 and later
2909
2910@item @emph{Class}:
2911Inquiry function
2912
2913@item @emph{Syntax}:
2914@code{RESULT = BIT_SIZE(I)}
2915
2916@item @emph{Arguments}:
2917@multitable @columnfractions .15 .70
2918@item @var{I} @tab The type shall be @code{INTEGER}.
2919@end multitable
2920
2921@item @emph{Return value}:
2922The return value is of type @code{INTEGER}
2923
2924@item @emph{Example}:
2925@smallexample
2926program test_bit_size
2927    integer :: i = 123
2928    integer :: size
2929    size = bit_size(i)
2930    print *, size
2931end program test_bit_size
2932@end smallexample
2933@end table
2934
2935
2936
2937@node BLE
2938@section @code{BLE} --- Bitwise less than or equal to
2939@fnindex BLE
2940@cindex bitwise comparison
2941
2942@table @asis
2943@item @emph{Description}:
2944Determines whether an integral is a bitwise less than or equal to
2945another.
2946
2947@item @emph{Standard}:
2948Fortran 2008 and later
2949
2950@item @emph{Class}:
2951Elemental function
2952
2953@item @emph{Syntax}:
2954@code{RESULT = BLE(I, J)}
2955
2956@item @emph{Arguments}:
2957@multitable @columnfractions .15 .70
2958@item @var{I} @tab Shall be of @code{INTEGER} type.
2959@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2960as @var{I}.
2961@end multitable
2962
2963@item @emph{Return value}:
2964The return value is of type @code{LOGICAL} and of the default kind.
2965
2966@item @emph{See also}:
2967@ref{BGT}, @gol
2968@ref{BGE}, @gol
2969@ref{BLT}
2970@end table
2971
2972
2973
2974@node BLT
2975@section @code{BLT} --- Bitwise less than
2976@fnindex BLT
2977@cindex bitwise comparison
2978
2979@table @asis
2980@item @emph{Description}:
2981Determines whether an integral is a bitwise less than another.
2982
2983@item @emph{Standard}:
2984Fortran 2008 and later
2985
2986@item @emph{Class}:
2987Elemental function
2988
2989@item @emph{Syntax}:
2990@code{RESULT = BLT(I, J)}
2991
2992@item @emph{Arguments}:
2993@multitable @columnfractions .15 .70
2994@item @var{I} @tab Shall be of @code{INTEGER} type.
2995@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2996as @var{I}.
2997@end multitable
2998
2999@item @emph{Return value}:
3000The return value is of type @code{LOGICAL} and of the default kind.
3001
3002@item @emph{See also}:
3003@ref{BGE}, @gol
3004@ref{BGT}, @gol
3005@ref{BLE}
3006@end table
3007
3008
3009
3010@node BTEST
3011@section @code{BTEST} --- Bit test function
3012@fnindex BTEST
3013@fnindex BBTEST
3014@fnindex BITEST
3015@fnindex BJTEST
3016@fnindex BKTEST
3017@cindex bits, testing
3018
3019@table @asis
3020@item @emph{Description}:
3021@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
3022in @var{I} is set.  The counting of the bits starts at 0.
3023
3024@item @emph{Standard}:
3025Fortran 90 and later, has overloads that are GNU extensions
3026
3027@item @emph{Class}:
3028Elemental function
3029
3030@item @emph{Syntax}:
3031@code{RESULT = BTEST(I, POS)}
3032
3033@item @emph{Arguments}:
3034@multitable @columnfractions .15 .70
3035@item @var{I} @tab The type shall be @code{INTEGER}.
3036@item @var{POS} @tab The type shall be @code{INTEGER}.
3037@end multitable
3038
3039@item @emph{Return value}:
3040The return value is of type @code{LOGICAL}
3041
3042@item @emph{Example}:
3043@smallexample
3044program test_btest
3045    integer :: i = 32768 + 1024 + 64
3046    integer :: pos
3047    logical :: bool
3048    do pos=0,16
3049        bool = btest(i, pos)
3050        print *, pos, bool
3051    end do
3052end program test_btest
3053@end smallexample
3054
3055@item @emph{Specific names}:
3056@multitable @columnfractions .21 .28 .18 .30
3057@headitem Name           @tab Argument         @tab Return type             @tab Standard
3058@item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later
3059@item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
3060@item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
3061@item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
3062@item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
3063@end multitable
3064@end table
3065
3066@node C_ASSOCIATED
3067@section @code{C_ASSOCIATED} --- Status of a C pointer
3068@fnindex C_ASSOCIATED
3069@cindex association status, C pointer
3070@cindex pointer, C association status
3071
3072@table @asis
3073@item @emph{Description}:
3074@code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3075@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3076
3077@item @emph{Standard}:
3078Fortran 2003 and later
3079
3080@item @emph{Class}:
3081Inquiry function
3082
3083@item @emph{Syntax}:
3084@code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3085
3086@item @emph{Arguments}:
3087@multitable @columnfractions .15 .70
3088@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3089@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3090@end multitable
3091
3092@item @emph{Return value}:
3093The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3094@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3095point to different addresses.
3096
3097@item @emph{Example}:
3098@smallexample
3099subroutine association_test(a,b)
3100  use iso_c_binding, only: c_associated, c_loc, c_ptr
3101  implicit none
3102  real, pointer :: a
3103  type(c_ptr) :: b
3104  if(c_associated(b, c_loc(a))) &
3105     stop 'b and a do not point to same target'
3106end subroutine association_test
3107@end smallexample
3108
3109@item @emph{See also}:
3110@ref{C_LOC}, @gol
3111@ref{C_FUNLOC}
3112@end table
3113
3114
3115@node C_F_POINTER
3116@section @code{C_F_POINTER} --- Convert C into Fortran pointer
3117@fnindex C_F_POINTER
3118@cindex pointer, convert C to Fortran
3119
3120@table @asis
3121@item @emph{Description}:
3122@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3123@var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3124
3125@item @emph{Standard}:
3126Fortran 2003 and later
3127
3128@item @emph{Class}:
3129Subroutine
3130
3131@item @emph{Syntax}:
3132@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3133
3134@item @emph{Arguments}:
3135@multitable @columnfractions .15 .70
3136@item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
3137@code{INTENT(IN)}.
3138@item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
3139@code{INTENT(OUT)}.
3140@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3141with @code{INTENT(IN)}. It shall be present
3142if and only if @var{fptr} is an array. The size
3143must be equal to the rank of @var{fptr}.
3144@end multitable
3145
3146@item @emph{Example}:
3147@smallexample
3148program main
3149  use iso_c_binding
3150  implicit none
3151  interface
3152    subroutine my_routine(p) bind(c,name='myC_func')
3153      import :: c_ptr
3154      type(c_ptr), intent(out) :: p
3155    end subroutine
3156  end interface
3157  type(c_ptr) :: cptr
3158  real,pointer :: a(:)
3159  call my_routine(cptr)
3160  call c_f_pointer(cptr, a, [12])
3161end program main
3162@end smallexample
3163
3164@item @emph{See also}:
3165@ref{C_LOC}, @gol
3166@ref{C_F_PROCPOINTER}
3167@end table
3168
3169
3170@node C_F_PROCPOINTER
3171@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3172@fnindex C_F_PROCPOINTER
3173@cindex pointer, C address of pointers
3174
3175@table @asis
3176@item @emph{Description}:
3177@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3178@var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3179
3180@item @emph{Standard}:
3181Fortran 2003 and later
3182
3183@item @emph{Class}:
3184Subroutine
3185
3186@item @emph{Syntax}:
3187@code{CALL C_F_PROCPOINTER(cptr, fptr)}
3188
3189@item @emph{Arguments}:
3190@multitable @columnfractions .15 .70
3191@item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
3192@code{INTENT(IN)}.
3193@item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
3194@code{INTENT(OUT)}.
3195@end multitable
3196
3197@item @emph{Example}:
3198@smallexample
3199program main
3200  use iso_c_binding
3201  implicit none
3202  abstract interface
3203    function func(a)
3204      import :: c_float
3205      real(c_float), intent(in) :: a
3206      real(c_float) :: func
3207    end function
3208  end interface
3209  interface
3210     function getIterFunc() bind(c,name="getIterFunc")
3211       import :: c_funptr
3212       type(c_funptr) :: getIterFunc
3213     end function
3214  end interface
3215  type(c_funptr) :: cfunptr
3216  procedure(func), pointer :: myFunc
3217  cfunptr = getIterFunc()
3218  call c_f_procpointer(cfunptr, myFunc)
3219end program main
3220@end smallexample
3221
3222@item @emph{See also}:
3223@ref{C_LOC}, @gol
3224@ref{C_F_POINTER}
3225@end table
3226
3227
3228@node C_FUNLOC
3229@section @code{C_FUNLOC} --- Obtain the C address of a procedure
3230@fnindex C_FUNLOC
3231@cindex pointer, C address of procedures
3232
3233@table @asis
3234@item @emph{Description}:
3235@code{C_FUNLOC(x)} determines the C address of the argument.
3236
3237@item @emph{Standard}:
3238Fortran 2003 and later
3239
3240@item @emph{Class}:
3241Inquiry function
3242
3243@item @emph{Syntax}:
3244@code{RESULT = C_FUNLOC(x)}
3245
3246@item @emph{Arguments}:
3247@multitable @columnfractions .15 .70
3248@item @var{x} @tab Interoperable function or pointer to such function.
3249@end multitable
3250
3251@item @emph{Return value}:
3252The return value is of type @code{C_FUNPTR} and contains the C address
3253of the argument.
3254
3255@item @emph{Example}:
3256@smallexample
3257module x
3258  use iso_c_binding
3259  implicit none
3260contains
3261  subroutine sub(a) bind(c)
3262    real(c_float) :: a
3263    a = sqrt(a)+5.0
3264  end subroutine sub
3265end module x
3266program main
3267  use iso_c_binding
3268  use x
3269  implicit none
3270  interface
3271    subroutine my_routine(p) bind(c,name='myC_func')
3272      import :: c_funptr
3273      type(c_funptr), intent(in) :: p
3274    end subroutine
3275  end interface
3276  call my_routine(c_funloc(sub))
3277end program main
3278@end smallexample
3279
3280@item @emph{See also}:
3281@ref{C_ASSOCIATED}, @gol
3282@ref{C_LOC}, @gol
3283@ref{C_F_POINTER}, @gol
3284@ref{C_F_PROCPOINTER}
3285@end table
3286
3287
3288@node C_LOC
3289@section @code{C_LOC} --- Obtain the C address of an object
3290@fnindex C_LOC
3291@cindex procedure pointer, convert C to Fortran
3292
3293@table @asis
3294@item @emph{Description}:
3295@code{C_LOC(X)} determines the C address of the argument.
3296
3297@item @emph{Standard}:
3298Fortran 2003 and later
3299
3300@item @emph{Class}:
3301Inquiry function
3302
3303@item @emph{Syntax}:
3304@code{RESULT = C_LOC(X)}
3305
3306@item @emph{Arguments}:
3307@multitable @columnfractions .10 .75
3308@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.
3309
3310@end multitable
3311
3312@item @emph{Return value}:
3313The return value is of type @code{C_PTR} and contains the C address
3314of the argument.
3315
3316@item @emph{Example}:
3317@smallexample
3318subroutine association_test(a,b)
3319  use iso_c_binding, only: c_associated, c_loc, c_ptr
3320  implicit none
3321  real, pointer :: a
3322  type(c_ptr) :: b
3323  if(c_associated(b, c_loc(a))) &
3324     stop 'b and a do not point to same target'
3325end subroutine association_test
3326@end smallexample
3327
3328@item @emph{See also}:
3329@ref{C_ASSOCIATED}, @gol
3330@ref{C_FUNLOC}, @gol
3331@ref{C_F_POINTER}, @gol
3332@ref{C_F_PROCPOINTER}
3333@end table
3334
3335
3336@node C_SIZEOF
3337@section @code{C_SIZEOF} --- Size in bytes of an expression
3338@fnindex C_SIZEOF
3339@cindex expression size
3340@cindex size of an expression
3341
3342@table @asis
3343@item @emph{Description}:
3344@code{C_SIZEOF(X)} calculates the number of bytes of storage the
3345expression @code{X} occupies.
3346
3347@item @emph{Standard}:
3348Fortran 2008
3349
3350@item @emph{Class}:
3351Inquiry function of the module @code{ISO_C_BINDING}
3352
3353@item @emph{Syntax}:
3354@code{N = C_SIZEOF(X)}
3355
3356@item @emph{Arguments}:
3357@multitable @columnfractions .15 .70
3358@item @var{X} @tab The argument shall be an interoperable data entity.
3359@end multitable
3360
3361@item @emph{Return value}:
3362The return value is of type integer and of the system-dependent kind
3363@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3364number of bytes occupied by the argument.  If the argument has the
3365@code{POINTER} attribute, the number of bytes of the storage area pointed
3366to is returned.  If the argument is of a derived type with @code{POINTER}
3367or @code{ALLOCATABLE} components, the return value does not account for
3368the sizes of the data pointed to by these components.
3369
3370@item @emph{Example}:
3371@smallexample
3372   use iso_c_binding
3373   integer(c_int) :: i
3374   real(c_float) :: r, s(5)
3375   print *, (c_sizeof(s)/c_sizeof(r) == 5)
3376   end
3377@end smallexample
3378The example will print @code{T} unless you are using a platform
3379where default @code{REAL} variables are unusually padded.
3380
3381@item @emph{See also}:
3382@ref{SIZEOF}, @gol
3383@ref{STORAGE_SIZE}
3384@end table
3385
3386
3387@node CEILING
3388@section @code{CEILING} --- Integer ceiling function
3389@fnindex CEILING
3390@cindex ceiling
3391@cindex rounding, ceiling
3392
3393@table @asis
3394@item @emph{Description}:
3395@code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3396
3397@item @emph{Standard}:
3398Fortran 95 and later
3399
3400@item @emph{Class}:
3401Elemental function
3402
3403@item @emph{Syntax}:
3404@code{RESULT = CEILING(A [, KIND])}
3405
3406@item @emph{Arguments}:
3407@multitable @columnfractions .15 .70
3408@item @var{A} @tab The type shall be @code{REAL}.
3409@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3410expression indicating the kind parameter of the result.
3411@end multitable
3412
3413@item @emph{Return value}:
3414The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3415and a default-kind @code{INTEGER} otherwise.
3416
3417@item @emph{Example}:
3418@smallexample
3419program test_ceiling
3420    real :: x = 63.29
3421    real :: y = -63.59
3422    print *, ceiling(x) ! returns 64
3423    print *, ceiling(y) ! returns -63
3424end program test_ceiling
3425@end smallexample
3426
3427@item @emph{See also}:
3428@ref{FLOOR}, @gol
3429@ref{NINT}
3430@end table
3431
3432
3433
3434@node CHAR
3435@section @code{CHAR} --- Character conversion function
3436@fnindex CHAR
3437@cindex conversion, to character
3438
3439@table @asis
3440@item @emph{Description}:
3441@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3442
3443@item @emph{Standard}:
3444Fortran 77 and later
3445
3446@item @emph{Class}:
3447Elemental function
3448
3449@item @emph{Syntax}:
3450@code{RESULT = CHAR(I [, KIND])}
3451
3452@item @emph{Arguments}:
3453@multitable @columnfractions .15 .70
3454@item @var{I} @tab The type shall be @code{INTEGER}.
3455@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3456expression indicating the kind parameter of the result.
3457@end multitable
3458
3459@item @emph{Return value}:
3460The return value is of type @code{CHARACTER(1)}
3461
3462@item @emph{Example}:
3463@smallexample
3464program test_char
3465    integer :: i = 74
3466    character(1) :: c
3467    c = char(i)
3468    print *, i, c ! returns 'J'
3469end program test_char
3470@end smallexample
3471
3472@item @emph{Specific names}:
3473@multitable @columnfractions .19 .19 .25 .33
3474@headitem Name           @tab Argument         @tab Return type             @tab Standard
3475@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 and later
3476@end multitable
3477
3478@item @emph{Note}:
3479See @ref{ICHAR} for a discussion of converting between numerical values
3480and formatted string representations.
3481
3482@item @emph{See also}:
3483@ref{ACHAR}, @gol
3484@ref{IACHAR}, @gol
3485@ref{ICHAR}
3486
3487@end table
3488
3489
3490
3491@node CHDIR
3492@section @code{CHDIR} --- Change working directory
3493@fnindex CHDIR
3494@cindex system, working directory
3495
3496@table @asis
3497@item @emph{Description}:
3498Change current working directory to a specified path.
3499
3500This intrinsic is provided in both subroutine and function forms; however,
3501only one form can be used in any given program unit.
3502
3503@item @emph{Standard}:
3504GNU extension
3505
3506@item @emph{Class}:
3507Subroutine, function
3508
3509@item @emph{Syntax}:
3510@multitable @columnfractions .80
3511@item @code{CALL CHDIR(NAME [, STATUS])}
3512@item @code{STATUS = CHDIR(NAME)}
3513@end multitable
3514
3515@item @emph{Arguments}:
3516@multitable @columnfractions .15 .70
3517@item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
3518kind and shall specify a valid path within the file system.
3519@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3520kind.  Returns 0 on success, and a system specific and nonzero error code
3521otherwise.
3522@end multitable
3523
3524@item @emph{Example}:
3525@smallexample
3526PROGRAM test_chdir
3527  CHARACTER(len=255) :: path
3528  CALL getcwd(path)
3529  WRITE(*,*) TRIM(path)
3530  CALL chdir("/tmp")
3531  CALL getcwd(path)
3532  WRITE(*,*) TRIM(path)
3533END PROGRAM
3534@end smallexample
3535
3536@item @emph{See also}:
3537@ref{GETCWD}
3538@end table
3539
3540
3541
3542@node CHMOD
3543@section @code{CHMOD} --- Change access permissions of files
3544@fnindex CHMOD
3545@cindex file system, change access mode
3546
3547@table @asis
3548@item @emph{Description}:
3549@code{CHMOD} changes the permissions of a file.
3550
3551This intrinsic is provided in both subroutine and function forms; however,
3552only one form can be used in any given program unit.
3553
3554@item @emph{Standard}:
3555GNU extension
3556
3557@item @emph{Class}:
3558Subroutine, function
3559
3560@item @emph{Syntax}:
3561@multitable @columnfractions .80
3562@item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3563@item @code{STATUS = CHMOD(NAME, MODE)}
3564@end multitable
3565
3566@item @emph{Arguments}:
3567@multitable @columnfractions .15 .70
3568
3569@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3570file name. Trailing blanks are ignored unless the character
3571@code{achar(0)} is present, then all characters up to and excluding
3572@code{achar(0)} are used as the file name.
3573
3574@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3575file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3576as defined by the POSIX standard. The argument shall either be a string of
3577a nonnegative octal number or a symbolic mode.
3578
3579@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3580@code{0} on success and nonzero otherwise.
3581@end multitable
3582
3583@item @emph{Return value}:
3584In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3585otherwise.
3586
3587@item @emph{Example}:
3588@code{CHMOD} as subroutine
3589@smallexample
3590program chmod_test
3591  implicit none
3592  integer :: status
3593  call chmod('test.dat','u+x',status)
3594  print *, 'Status: ', status
3595end program chmod_test
3596@end smallexample
3597@code{CHMOD} as function:
3598@smallexample
3599program chmod_test
3600  implicit none
3601  integer :: status
3602  status = chmod('test.dat','u+x')
3603  print *, 'Status: ', status
3604end program chmod_test
3605@end smallexample
3606
3607@end table
3608
3609
3610
3611@node CMPLX
3612@section @code{CMPLX} --- Complex conversion function
3613@fnindex CMPLX
3614@cindex complex numbers, conversion to
3615@cindex conversion, to complex
3616
3617@table @asis
3618@item @emph{Description}:
3619@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3620the real component.  If @var{Y} is present it is converted to the imaginary
3621component.  If @var{Y} is not present then the imaginary component is set to
36220.0.  If @var{X} is complex then @var{Y} must not be present.
3623
3624@item @emph{Standard}:
3625Fortran 77 and later
3626
3627@item @emph{Class}:
3628Elemental function
3629
3630@item @emph{Syntax}:
3631@code{RESULT = CMPLX(X [, Y [, KIND]])}
3632
3633@item @emph{Arguments}:
3634@multitable @columnfractions .15 .70
3635@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3636or @code{COMPLEX}.
3637@item @var{Y} @tab (Optional; only allowed if @var{X} is not
3638@code{COMPLEX}.)  May be @code{INTEGER} or @code{REAL}.
3639@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3640expression indicating the kind parameter of the result.
3641@end multitable
3642
3643@item @emph{Return value}:
3644The return value is of @code{COMPLEX} type, with a kind equal to
3645@var{KIND} if it is specified.  If @var{KIND} is not specified, the
3646result is of the default @code{COMPLEX} kind, regardless of the kinds of
3647@var{X} and @var{Y}.
3648
3649@item @emph{Example}:
3650@smallexample
3651program test_cmplx
3652    integer :: i = 42
3653    real :: x = 3.14
3654    complex :: z
3655    z = cmplx(i, x)
3656    print *, z, cmplx(x)
3657end program test_cmplx
3658@end smallexample
3659
3660@item @emph{See also}:
3661@ref{COMPLEX}
3662@end table
3663
3664
3665
3666@node CO_BROADCAST
3667@section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3668@fnindex CO_BROADCAST
3669@cindex Collectives, value broadcasting
3670
3671@table @asis
3672@item @emph{Description}:
3673@code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3674image index @code{SOURCE_IMAGE} to all images in the current team.  @var{A}
3675becomes defined as if by intrinsic assignment.  If the execution was
3676successful and @var{STAT} is present, it is assigned the value zero.  If the
3677execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3678@var{ERRMSG} gets assigned a value describing the occurred error.
3679
3680@item @emph{Standard}:
3681Technical Specification (TS) 18508 or later
3682
3683@item @emph{Class}:
3684Collective subroutine
3685
3686@item @emph{Syntax}:
3687@code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3688
3689@item @emph{Arguments}:
3690@multitable @columnfractions .20 .65
3691@item @var{A}            @tab INTENT(INOUT) argument; shall have the same
3692dynamic type and type parameters on all images of the current team. If it
3693is an array, it shall have the same shape on all images.
3694@item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3695It shall have the same value on all images and refer to an
3696image of the current team.
3697@item @var{STAT}         @tab (optional) a scalar integer variable
3698@item @var{ERRMSG}       @tab (optional) a scalar character variable
3699@end multitable
3700
3701@item @emph{Example}:
3702@smallexample
3703program test
3704  integer :: val(3)
3705  if (this_image() == 1) then
3706    val = [1, 5, 3]
3707  end if
3708  call co_broadcast (val, source_image=1)
3709  print *, this_image, ":", val
3710end program test
3711@end smallexample
3712
3713@item @emph{See also}:
3714@ref{CO_MAX}, @gol
3715@ref{CO_MIN}, @gol
3716@ref{CO_SUM}, @gol
3717@ref{CO_REDUCE}
3718@end table
3719
3720
3721
3722@node CO_MAX
3723@section @code{CO_MAX} --- Maximal value on the current set of images
3724@fnindex CO_MAX
3725@cindex Collectives, maximal value
3726
3727@table @asis
3728@item @emph{Description}:
3729@code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3730images of the current team.  If @var{RESULT_IMAGE} is present, the maximum
3731values are returned in @var{A} on the specified image only and the value
3732of @var{A} on the other images become undefined.  If @var{RESULT_IMAGE} is
3733not present, the value is returned on all images.  If the execution was
3734successful and @var{STAT} is present, it is assigned the value zero.  If the
3735execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3736@var{ERRMSG} gets assigned a value describing the occurred error.
3737
3738@item @emph{Standard}:
3739Technical Specification (TS) 18508 or later
3740
3741@item @emph{Class}:
3742Collective subroutine
3743
3744@item @emph{Syntax}:
3745@code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3746
3747@item @emph{Arguments}:
3748@multitable @columnfractions .20 .65
3749@item @var{A}            @tab shall be an integer, real or character variable,
3750which has the same type and type parameters on all images of the team.
3751@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3752present, it shall have the same value on all images and refer to an
3753image of the current team.
3754@item @var{STAT}         @tab (optional) a scalar integer variable
3755@item @var{ERRMSG}       @tab (optional) a scalar character variable
3756@end multitable
3757
3758@item @emph{Example}:
3759@smallexample
3760program test
3761  integer :: val
3762  val = this_image ()
3763  call co_max (val, result_image=1)
3764  if (this_image() == 1) then
3765    write(*,*) "Maximal value", val  ! prints num_images()
3766  end if
3767end program test
3768@end smallexample
3769
3770@item @emph{See also}:
3771@ref{CO_MIN}, @gol
3772@ref{CO_SUM}, @gol
3773@ref{CO_REDUCE}, @gol
3774@ref{CO_BROADCAST}
3775@end table
3776
3777
3778
3779@node CO_MIN
3780@section @code{CO_MIN} --- Minimal value on the current set of images
3781@fnindex CO_MIN
3782@cindex Collectives, minimal value
3783
3784@table @asis
3785@item @emph{Description}:
3786@code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3787images of the current team.  If @var{RESULT_IMAGE} is present, the minimal
3788values are returned in @var{A} on the specified image only and the value
3789of @var{A} on the other images become undefined.  If @var{RESULT_IMAGE} is
3790not present, the value is returned on all images.  If the execution was
3791successful and @var{STAT} is present, it is assigned the value zero.  If the
3792execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3793@var{ERRMSG} gets assigned a value describing the occurred error.
3794
3795@item @emph{Standard}:
3796Technical Specification (TS) 18508 or later
3797
3798@item @emph{Class}:
3799Collective subroutine
3800
3801@item @emph{Syntax}:
3802@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3803
3804@item @emph{Arguments}:
3805@multitable @columnfractions .20 .65
3806@item @var{A}            @tab shall be an integer, real or character variable,
3807which has the same type and type parameters on all images of the team.
3808@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3809present, it shall have the same value on all images and refer to an
3810image of the current team.
3811@item @var{STAT}         @tab (optional) a scalar integer variable
3812@item @var{ERRMSG}       @tab (optional) a scalar character variable
3813@end multitable
3814
3815@item @emph{Example}:
3816@smallexample
3817program test
3818  integer :: val
3819  val = this_image ()
3820  call co_min (val, result_image=1)
3821  if (this_image() == 1) then
3822    write(*,*) "Minimal value", val  ! prints 1
3823  end if
3824end program test
3825@end smallexample
3826
3827@item @emph{See also}:
3828@ref{CO_MAX}, @gol
3829@ref{CO_SUM}, @gol
3830@ref{CO_REDUCE}, @gol
3831@ref{CO_BROADCAST}
3832@end table
3833
3834
3835
3836@node CO_REDUCE
3837@section @code{CO_REDUCE} --- Reduction of values on the current set of images
3838@fnindex CO_REDUCE
3839@cindex Collectives, generic reduction
3840
3841@table @asis
3842@item @emph{Description}:
3843@code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3844on all images of the current team.  The pure function passed as @var{OPERATION}
3845is used to pairwise reduce the values of @var{A} by passing either the value
3846of @var{A} of different images or the result values of such a reduction as
3847argument.  If @var{A} is an array, the deduction is done element wise. If
3848@var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3849the specified image only and the value of @var{A} on the other images become
3850undefined.  If @var{RESULT_IMAGE} is not present, the value is returned on all
3851images.  If the execution was successful and @var{STAT} is present, it is
3852assigned the value zero.  If the execution failed, @var{STAT} gets assigned
3853a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3854the occurred error.
3855
3856@item @emph{Standard}:
3857Technical Specification (TS) 18508 or later
3858
3859@item @emph{Class}:
3860Collective subroutine
3861
3862@item @emph{Syntax}:
3863@code{CALL CO_REDUCE(A, OPERATION, [, RESULT_IMAGE, STAT, ERRMSG])}
3864
3865@item @emph{Arguments}:
3866@multitable @columnfractions .20 .65
3867@item @var{A}            @tab is an @code{INTENT(INOUT)} argument and shall be
3868nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3869it shall be associated.  @var{A} shall have the same type and type parameters on
3870all images of the team; if it is an array, it shall have the same shape on all
3871images.
3872@item @var{OPERATION}     @tab pure function with two scalar nonallocatable
3873arguments, which shall be nonpolymorphic and have the same type and type
3874parameters as @var{A}.  The function shall return a nonallocatable scalar of
3875the same type and type parameters as @var{A}.  The function shall be the same on
3876all images and with regards to the arguments mathematically commutative and
3877associative.  Note that @var{OPERATION} may not be an elemental function, unless
3878it is an intrisic function.
3879@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3880present, it shall have the same value on all images and refer to an
3881image of the current team.
3882@item @var{STAT}         @tab (optional) a scalar integer variable
3883@item @var{ERRMSG}       @tab (optional) a scalar character variable
3884@end multitable
3885
3886@item @emph{Example}:
3887@smallexample
3888program test
3889  integer :: val
3890  val = this_image ()
3891  call co_reduce (val, result_image=1, operation=myprod)
3892  if (this_image() == 1) then
3893    write(*,*) "Product value", val  ! prints num_images() factorial
3894  end if
3895contains
3896  pure function myprod(a, b)
3897    integer, value :: a, b
3898    integer :: myprod
3899    myprod = a * b
3900  end function myprod
3901end program test
3902@end smallexample
3903
3904@item @emph{Note}:
3905While the rules permit in principle an intrinsic function, none of the
3906intrinsics in the standard fulfill the criteria of having a specific
3907function, which takes two arguments of the same type and returning that
3908type as result.
3909
3910@item @emph{See also}:
3911@ref{CO_MIN}, @gol
3912@ref{CO_MAX}, @gol
3913@ref{CO_SUM}, @gol
3914@ref{CO_BROADCAST}
3915@end table
3916
3917
3918
3919@node CO_SUM
3920@section @code{CO_SUM} --- Sum of values on the current set of images
3921@fnindex CO_SUM
3922@cindex Collectives, sum of values
3923
3924@table @asis
3925@item @emph{Description}:
3926@code{CO_SUM} sums up the values of each element of @var{A} on all
3927images of the current team.  If @var{RESULT_IMAGE} is present, the summed-up
3928values are returned in @var{A} on the specified image only and the value
3929of @var{A} on the other images become undefined.  If @var{RESULT_IMAGE} is
3930not present, the value is returned on all images.  If the execution was
3931successful and @var{STAT} is present, it is assigned the value zero.  If the
3932execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3933@var{ERRMSG} gets assigned a value describing the occurred error.
3934
3935@item @emph{Standard}:
3936Technical Specification (TS) 18508 or later
3937
3938@item @emph{Class}:
3939Collective subroutine
3940
3941@item @emph{Syntax}:
3942@code{CALL CO_SUM(A [, RESULT_IMAGE, STAT, ERRMSG])}
3943
3944@item @emph{Arguments}:
3945@multitable @columnfractions .20 .65
3946@item @var{A}            @tab shall be an integer, real or complex variable,
3947which has the same type and type parameters on all images of the team.
3948@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3949present, it shall have the same value on all images and refer to an
3950image of the current team.
3951@item @var{STAT}         @tab (optional) a scalar integer variable
3952@item @var{ERRMSG}       @tab (optional) a scalar character variable
3953@end multitable
3954
3955@item @emph{Example}:
3956@smallexample
3957program test
3958  integer :: val
3959  val = this_image ()
3960  call co_sum (val, result_image=1)
3961  if (this_image() == 1) then
3962    write(*,*) "The sum is ", val ! prints (n**2 + n)/2,
3963                                  ! with n = num_images()
3964  end if
3965end program test
3966@end smallexample
3967
3968@item @emph{See also}:
3969@ref{CO_MAX}, @gol
3970@ref{CO_MIN}, @gol
3971@ref{CO_REDUCE}, @gol
3972@ref{CO_BROADCAST}
3973@end table
3974
3975
3976
3977@node COMMAND_ARGUMENT_COUNT
3978@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3979@fnindex COMMAND_ARGUMENT_COUNT
3980@cindex command-line arguments
3981@cindex command-line arguments, number of
3982@cindex arguments, to program
3983
3984@table @asis
3985@item @emph{Description}:
3986@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3987command line when the containing program was invoked.
3988
3989@item @emph{Standard}:
3990Fortran 2003 and later
3991
3992@item @emph{Class}:
3993Inquiry function
3994
3995@item @emph{Syntax}:
3996@code{RESULT = COMMAND_ARGUMENT_COUNT()}
3997
3998@item @emph{Arguments}:
3999@multitable @columnfractions .15 .70
4000@item None
4001@end multitable
4002
4003@item @emph{Return value}:
4004The return value is an @code{INTEGER} of default kind.
4005
4006@item @emph{Example}:
4007@smallexample
4008program test_command_argument_count
4009    integer :: count
4010    count = command_argument_count()
4011    print *, count
4012end program test_command_argument_count
4013@end smallexample
4014
4015@item @emph{See also}:
4016@ref{GET_COMMAND}, @gol
4017@ref{GET_COMMAND_ARGUMENT}
4018@end table
4019
4020
4021
4022@node COMPILER_OPTIONS
4023@section @code{COMPILER_OPTIONS} --- Options passed to the compiler
4024@fnindex COMPILER_OPTIONS
4025@cindex flags inquiry function
4026@cindex options inquiry function
4027@cindex compiler flags inquiry function
4028
4029@table @asis
4030@item @emph{Description}:
4031@code{COMPILER_OPTIONS} returns a string with the options used for
4032compiling.
4033
4034@item @emph{Standard}:
4035Fortran 2008
4036
4037@item @emph{Class}:
4038Inquiry function of the module @code{ISO_FORTRAN_ENV}
4039
4040@item @emph{Syntax}:
4041@code{STR = COMPILER_OPTIONS()}
4042
4043@item @emph{Arguments}:
4044None
4045
4046@item @emph{Return value}:
4047The return value is a default-kind string with system-dependent length.
4048It contains the compiler flags used to compile the file, which called
4049the @code{COMPILER_OPTIONS} intrinsic.
4050
4051@item @emph{Example}:
4052@smallexample
4053   use iso_fortran_env
4054   print '(4a)', 'This file was compiled by ', &
4055                 compiler_version(), ' using the options ', &
4056                 compiler_options()
4057   end
4058@end smallexample
4059
4060@item @emph{See also}:
4061@ref{COMPILER_VERSION}, @gol
4062@ref{ISO_FORTRAN_ENV}
4063@end table
4064
4065
4066
4067@node COMPILER_VERSION
4068@section @code{COMPILER_VERSION} --- Compiler version string
4069@fnindex COMPILER_VERSION
4070@cindex compiler, name and version
4071@cindex version of the compiler
4072
4073@table @asis
4074@item @emph{Description}:
4075@code{COMPILER_VERSION} returns a string with the name and the
4076version of the compiler.
4077
4078@item @emph{Standard}:
4079Fortran 2008
4080
4081@item @emph{Class}:
4082Inquiry function of the module @code{ISO_FORTRAN_ENV}
4083
4084@item @emph{Syntax}:
4085@code{STR = COMPILER_VERSION()}
4086
4087@item @emph{Arguments}:
4088None
4089
4090@item @emph{Return value}:
4091The return value is a default-kind string with system-dependent length.
4092It contains the name of the compiler and its version number.
4093
4094@item @emph{Example}:
4095@smallexample
4096   use iso_fortran_env
4097   print '(4a)', 'This file was compiled by ', &
4098                 compiler_version(), ' using the options ', &
4099                 compiler_options()
4100   end
4101@end smallexample
4102
4103@item @emph{See also}:
4104@ref{COMPILER_OPTIONS}, @gol
4105@ref{ISO_FORTRAN_ENV}
4106@end table
4107
4108
4109
4110@node COMPLEX
4111@section @code{COMPLEX} --- Complex conversion function
4112@fnindex COMPLEX
4113@cindex complex numbers, conversion to
4114@cindex conversion, to complex
4115
4116@table @asis
4117@item @emph{Description}:
4118@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4119to the real component and @var{Y} is converted to the imaginary
4120component.
4121
4122@item @emph{Standard}:
4123GNU extension
4124
4125@item @emph{Class}:
4126Elemental function
4127
4128@item @emph{Syntax}:
4129@code{RESULT = COMPLEX(X, Y)}
4130
4131@item @emph{Arguments}:
4132@multitable @columnfractions .15 .70
4133@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4134@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4135@end multitable
4136
4137@item @emph{Return value}:
4138If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4139value is of default @code{COMPLEX} type.
4140
4141If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4142type and one is of @code{INTEGER} type, then the return value is of
4143@code{COMPLEX} type with a kind equal to that of the @code{REAL}
4144argument with the highest precision.
4145
4146@item @emph{Example}:
4147@smallexample
4148program test_complex
4149    integer :: i = 42
4150    real :: x = 3.14
4151    print *, complex(i, x)
4152end program test_complex
4153@end smallexample
4154
4155@item @emph{See also}:
4156@ref{CMPLX}
4157@end table
4158
4159
4160
4161@node CONJG
4162@section @code{CONJG} --- Complex conjugate function
4163@fnindex CONJG
4164@fnindex DCONJG
4165@cindex complex conjugate
4166
4167@table @asis
4168@item @emph{Description}:
4169@code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
4170then the result is @code{(x, -y)}
4171
4172@item @emph{Standard}:
4173Fortran 77 and later, has an overload that is a GNU extension
4174
4175@item @emph{Class}:
4176Elemental function
4177
4178@item @emph{Syntax}:
4179@code{Z = CONJG(Z)}
4180
4181@item @emph{Arguments}:
4182@multitable @columnfractions .15 .70
4183@item @var{Z} @tab The type shall be @code{COMPLEX}.
4184@end multitable
4185
4186@item @emph{Return value}:
4187The return value is of type @code{COMPLEX}.
4188
4189@item @emph{Example}:
4190@smallexample
4191program test_conjg
4192    complex :: z = (2.0, 3.0)
4193    complex(8) :: dz = (2.71_8, -3.14_8)
4194    z= conjg(z)
4195    print *, z
4196    dz = dconjg(dz)
4197    print *, dz
4198end program test_conjg
4199@end smallexample
4200
4201@item @emph{Specific names}:
4202@multitable @columnfractions .20 .23 .20 .33
4203@headitem Name             @tab Argument             @tab Return type       @tab Standard
4204@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)} @tab GNU extension
4205@end multitable
4206@end table
4207
4208
4209
4210@node COS
4211@section @code{COS} --- Cosine function
4212@fnindex COS
4213@fnindex DCOS
4214@fnindex CCOS
4215@fnindex ZCOS
4216@fnindex CDCOS
4217@cindex trigonometric function, cosine
4218@cindex cosine
4219
4220@table @asis
4221@item @emph{Description}:
4222@code{COS(X)} computes the cosine of @var{X}.
4223
4224@item @emph{Standard}:
4225Fortran 77 and later, has overloads that are GNU extensions
4226
4227@item @emph{Class}:
4228Elemental function
4229
4230@item @emph{Syntax}:
4231@code{RESULT = COS(X)}
4232
4233@item @emph{Arguments}:
4234@multitable @columnfractions .15 .70
4235@item @var{X} @tab The type shall be @code{REAL} or
4236@code{COMPLEX}.
4237@end multitable
4238
4239@item @emph{Return value}:
4240The return value is of the same type and kind as @var{X}. The real part
4241of the result is in radians. If @var{X} is of the type @code{REAL},
4242the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4243
4244@item @emph{Example}:
4245@smallexample
4246program test_cos
4247  real :: x = 0.0
4248  x = cos(x)
4249end program test_cos
4250@end smallexample
4251
4252@item @emph{Specific names}:
4253@multitable @columnfractions .20 .23 .20 .33
4254@headitem Name            @tab Argument            @tab Return type       @tab Standard
4255@item @code{COS(X)}   @tab @code{REAL(4) X}    @tab @code{REAL(4)}    @tab Fortran 77 and later
4256@item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
4257@item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4258@item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4259@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4260@end multitable
4261
4262@item @emph{See also}:
4263Inverse function: @gol
4264@ref{ACOS} @gol
4265Degrees function: @gol
4266@ref{COSD}
4267@end table
4268
4269
4270
4271@node COSD
4272@section @code{COSD} --- Cosine function, degrees
4273@fnindex COSD
4274@fnindex DCOSD
4275@fnindex CCOSD
4276@fnindex ZCOSD
4277@fnindex CDCOSD
4278@cindex trigonometric function, cosine, degrees
4279@cindex cosine, degrees
4280
4281@table @asis
4282@item @emph{Description}:
4283@code{COSD(X)} computes the cosine of @var{X} in degrees.
4284
4285This function is for compatibility only and should be avoided in favor of
4286standard constructs wherever possible.
4287
4288@item @emph{Standard}:
4289GNU extension, enabled with @option{-fdec-math}.
4290
4291@item @emph{Class}:
4292Elemental function
4293
4294@item @emph{Syntax}:
4295@code{RESULT = COSD(X)}
4296
4297@item @emph{Arguments}:
4298@multitable @columnfractions .15 .70
4299@item @var{X} @tab The type shall be @code{REAL} or
4300@code{COMPLEX}.
4301@end multitable
4302
4303@item @emph{Return value}:
4304The return value is of the same type and kind as @var{X}. The real part
4305of the result is in degrees.  If @var{X} is of the type @code{REAL},
4306the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4307
4308@item @emph{Example}:
4309@smallexample
4310program test_cosd
4311  real :: x = 0.0
4312  x = cosd(x)
4313end program test_cosd
4314@end smallexample
4315
4316@item @emph{Specific names}:
4317@multitable @columnfractions .20 .23 .20 .33
4318@headitem Name            @tab Argument            @tab Return type       @tab Standard
4319@item @code{COSD(X)}   @tab @code{REAL(4) X}    @tab @code{REAL(4)}    @tab GNU extension
4320@item @code{DCOSD(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab GNU extension
4321@item @code{CCOSD(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
4322@item @code{ZCOSD(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4323@item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4324@end multitable
4325
4326@item @emph{See also}:
4327Inverse function: @gol
4328@ref{ACOSD} @gol
4329Radians function: @gol
4330@ref{COS}
4331@end table
4332
4333
4334
4335@node COSH
4336@section @code{COSH} --- Hyperbolic cosine function
4337@fnindex COSH
4338@fnindex DCOSH
4339@cindex hyperbolic cosine
4340@cindex hyperbolic function, cosine
4341@cindex cosine, hyperbolic
4342
4343@table @asis
4344@item @emph{Description}:
4345@code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4346
4347@item @emph{Standard}:
4348Fortran 77 and later, for a complex argument Fortran 2008 or later
4349
4350@item @emph{Class}:
4351Elemental function
4352
4353@item @emph{Syntax}:
4354@code{X = COSH(X)}
4355
4356@item @emph{Arguments}:
4357@multitable @columnfractions .15 .70
4358@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4359@end multitable
4360
4361@item @emph{Return value}:
4362The return value has same type and kind as @var{X}. If @var{X} is
4363complex, the imaginary part of the result is in radians. If @var{X}
4364is @code{REAL}, the return value has a lower bound of one,
4365@math{\cosh (x) \geq 1}.
4366
4367@item @emph{Example}:
4368@smallexample
4369program test_cosh
4370  real(8) :: x = 1.0_8
4371  x = cosh(x)
4372end program test_cosh
4373@end smallexample
4374
4375@item @emph{Specific names}:
4376@multitable @columnfractions .20 .23 .20 .33
4377@headitem Name            @tab Argument          @tab Return type       @tab Standard
4378@item @code{COSH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
4379@item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
4380@end multitable
4381
4382@item @emph{See also}:
4383Inverse function: @gol
4384@ref{ACOSH}
4385@end table
4386
4387
4388
4389@node COTAN
4390@section @code{COTAN} --- Cotangent function
4391@fnindex COTAN
4392@fnindex DCOTAN
4393@cindex trigonometric function, cotangent
4394@cindex cotangent
4395
4396@table @asis
4397@item @emph{Description}:
4398@code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4399divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4400
4401This function is for compatibility only and should be avoided in favor of
4402standard constructs wherever possible.
4403
4404@item @emph{Standard}:
4405GNU extension, enabled with @option{-fdec-math}.
4406
4407@item @emph{Class}:
4408Elemental function
4409
4410@item @emph{Syntax}:
4411@code{RESULT = COTAN(X)}
4412
4413@item @emph{Arguments}:
4414@multitable @columnfractions .15 .70
4415@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4416@end multitable
4417
4418@item @emph{Return value}:
4419The return value has same type and kind as @var{X}, and its value is in radians.
4420
4421@item @emph{Example}:
4422@smallexample
4423program test_cotan
4424  real(8) :: x = 0.165_8
4425  x = cotan(x)
4426end program test_cotan
4427@end smallexample
4428
4429@item @emph{Specific names}:
4430@multitable @columnfractions .20 .23 .20 .33
4431@headitem Name            @tab Argument          @tab Return type     @tab Standard
4432@item @code{COTAN(X)}   @tab @code{REAL(4) X}  @tab @code{REAL(4)}  @tab GNU extension
4433@item @code{DCOTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab GNU extension
4434@end multitable
4435
4436@item @emph{See also}:
4437Converse function: @gol
4438@ref{TAN} @gol
4439Degrees function: @gol
4440@ref{COTAND}
4441@end table
4442
4443
4444
4445@node COTAND
4446@section @code{COTAND} --- Cotangent function, degrees
4447@fnindex COTAND
4448@fnindex DCOTAND
4449@cindex trigonometric function, cotangent, degrees
4450@cindex cotangent, degrees
4451
4452@table @asis
4453@item @emph{Description}:
4454@code{COTAND(X)} computes the cotangent of @var{X} in degrees.  Equivalent to
4455@code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4456
4457@item @emph{Standard}:
4458GNU extension, enabled with @option{-fdec-math}.
4459
4460This function is for compatibility only and should be avoided in favor of
4461standard constructs wherever possible.
4462
4463@item @emph{Class}:
4464Elemental function
4465
4466@item @emph{Syntax}:
4467@code{RESULT = COTAND(X)}
4468
4469@item @emph{Arguments}:
4470@multitable @columnfractions .15 .70
4471@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4472@end multitable
4473
4474@item @emph{Return value}:
4475The return value has same type and kind as @var{X}, and its value is in degrees.
4476
4477@item @emph{Example}:
4478@smallexample
4479program test_cotand
4480  real(8) :: x = 0.165_8
4481  x = cotand(x)
4482end program test_cotand
4483@end smallexample
4484
4485@item @emph{Specific names}:
4486@multitable @columnfractions .20 .23 .20 .33
4487@headitem Name            @tab Argument          @tab Return type     @tab Standard
4488@item @code{COTAND(X)}   @tab @code{REAL(4) X}  @tab @code{REAL(4)}  @tab GNU extension
4489@item @code{DCOTAND(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab GNU extension
4490@end multitable
4491
4492@item @emph{See also}:
4493Converse function: @gol
4494@ref{TAND} @gol
4495Radians function: @gol
4496@ref{COTAN}
4497@end table
4498
4499
4500
4501@node COUNT
4502@section @code{COUNT} --- Count function
4503@fnindex COUNT
4504@cindex array, conditionally count elements
4505@cindex array, element counting
4506@cindex array, number of elements
4507
4508@table @asis
4509@item @emph{Description}:
4510
4511Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4512or, if the @var{DIM} argument is supplied, counts the number of
4513elements along each row of the array in the @var{DIM} direction.
4514If the array has zero size, or all of the elements of @var{MASK} are
4515@code{.FALSE.}, then the result is @code{0}.
4516
4517@item @emph{Standard}:
4518Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
4519
4520@item @emph{Class}:
4521Transformational function
4522
4523@item @emph{Syntax}:
4524@code{RESULT = COUNT(MASK [, DIM, KIND])}
4525
4526@item @emph{Arguments}:
4527@multitable @columnfractions .15 .70
4528@item @var{MASK} @tab The type shall be @code{LOGICAL}.
4529@item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
4530@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4531expression indicating the kind parameter of the result.
4532@end multitable
4533
4534@item @emph{Return value}:
4535The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4536@var{KIND} is absent, the return value is of default integer kind.
4537If @var{DIM} is present, the result is an array with a rank one less
4538than the rank of @var{ARRAY}, and a size corresponding to the shape
4539of @var{ARRAY} with the @var{DIM} dimension removed.
4540
4541@item @emph{Example}:
4542@smallexample
4543program test_count
4544    integer, dimension(2,3) :: a, b
4545    logical, dimension(2,3) :: mask
4546    a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4547    b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4548    print '(3i3)', a(1,:)
4549    print '(3i3)', a(2,:)
4550    print *
4551    print '(3i3)', b(1,:)
4552    print '(3i3)', b(2,:)
4553    print *
4554    mask = a.ne.b
4555    print '(3l3)', mask(1,:)
4556    print '(3l3)', mask(2,:)
4557    print *
4558    print '(3i3)', count(mask)
4559    print *
4560    print '(3i3)', count(mask, 1)
4561    print *
4562    print '(3i3)', count(mask, 2)
4563end program test_count
4564@end smallexample
4565@end table
4566
4567
4568
4569@node CPU_TIME
4570@section @code{CPU_TIME} --- CPU elapsed time in seconds
4571@fnindex CPU_TIME
4572@cindex time, elapsed
4573
4574@table @asis
4575@item @emph{Description}:
4576Returns a @code{REAL} value representing the elapsed CPU time in
4577seconds.  This is useful for testing segments of code to determine
4578execution time.
4579
4580If a time source is available, time will be reported with microsecond
4581resolution. If no time source is available, @var{TIME} is set to
4582@code{-1.0}.
4583
4584Note that @var{TIME} may contain a, system dependent, arbitrary offset
4585and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4586value is meaningless, only differences between subsequent calls to
4587this subroutine, as shown in the example below, should be used.
4588
4589
4590@item @emph{Standard}:
4591Fortran 95 and later
4592
4593@item @emph{Class}:
4594Subroutine
4595
4596@item @emph{Syntax}:
4597@code{CALL CPU_TIME(TIME)}
4598
4599@item @emph{Arguments}:
4600@multitable @columnfractions .15 .70
4601@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4602@end multitable
4603
4604@item @emph{Return value}:
4605None
4606
4607@item @emph{Example}:
4608@smallexample
4609program test_cpu_time
4610    real :: start, finish
4611    call cpu_time(start)
4612        ! put code to test here
4613    call cpu_time(finish)
4614    print '("Time = ",f6.3," seconds.")',finish-start
4615end program test_cpu_time
4616@end smallexample
4617
4618@item @emph{See also}:
4619@ref{SYSTEM_CLOCK}, @gol
4620@ref{DATE_AND_TIME}
4621@end table
4622
4623
4624
4625@node CSHIFT
4626@section @code{CSHIFT} --- Circular shift elements of an array
4627@fnindex CSHIFT
4628@cindex array, shift circularly
4629@cindex array, permutation
4630@cindex array, rotate
4631
4632@table @asis
4633@item @emph{Description}:
4634@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4635@var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
4636taken to be @code{1}.  @var{DIM} is a scalar of type @code{INTEGER} in the
4637range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4638If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4639by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
4640sections of @var{ARRAY} along the given dimension are shifted.  Elements
4641shifted out one end of each rank one section are shifted back in the other end.
4642
4643@item @emph{Standard}:
4644Fortran 90 and later
4645
4646@item @emph{Class}:
4647Transformational function
4648
4649@item @emph{Syntax}:
4650@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4651
4652@item @emph{Arguments}:
4653@multitable @columnfractions .15 .70
4654@item @var{ARRAY}  @tab Shall be an array of any type.
4655@item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
4656@item @var{DIM}    @tab The type shall be @code{INTEGER}.
4657@end multitable
4658
4659@item @emph{Return value}:
4660Returns an array of same type and rank as the @var{ARRAY} argument.
4661
4662@item @emph{Example}:
4663@smallexample
4664program test_cshift
4665    integer, dimension(3,3) :: a
4666    a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4667    print '(3i3)', a(1,:)
4668    print '(3i3)', a(2,:)
4669    print '(3i3)', a(3,:)
4670    a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4671    print *
4672    print '(3i3)', a(1,:)
4673    print '(3i3)', a(2,:)
4674    print '(3i3)', a(3,:)
4675end program test_cshift
4676@end smallexample
4677@end table
4678
4679
4680
4681@node CTIME
4682@section @code{CTIME} --- Convert a time into a string
4683@fnindex CTIME
4684@cindex time, conversion to string
4685@cindex conversion, to string
4686
4687@table @asis
4688@item @emph{Description}:
4689@code{CTIME} converts a system time value, such as returned by
4690@ref{TIME8}, to a string. The output will be of the form @samp{Sat
4691Aug 19 18:13:14 1995}.
4692
4693This intrinsic is provided in both subroutine and function forms; however,
4694only one form can be used in any given program unit.
4695
4696@item @emph{Standard}:
4697GNU extension
4698
4699@item @emph{Class}:
4700Subroutine, function
4701
4702@item @emph{Syntax}:
4703@multitable @columnfractions .80
4704@item @code{CALL CTIME(TIME, RESULT)}.
4705@item @code{RESULT = CTIME(TIME)}.
4706@end multitable
4707
4708@item @emph{Arguments}:
4709@multitable @columnfractions .15 .70
4710@item @var{TIME}    @tab The type shall be of type @code{INTEGER}.
4711@item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
4712of default kind. It is an @code{INTENT(OUT)} argument. If the length
4713of this variable is too short for the time and date string to fit
4714completely, it will be blank on procedure return.
4715@end multitable
4716
4717@item @emph{Return value}:
4718The converted date and time as a string.
4719
4720@item @emph{Example}:
4721@smallexample
4722program test_ctime
4723    integer(8) :: i
4724    character(len=30) :: date
4725    i = time8()
4726
4727    ! Do something, main part of the program
4728
4729    call ctime(i,date)
4730    print *, 'Program was started on ', date
4731end program test_ctime
4732@end smallexample
4733
4734@item @emph{See Also}:
4735@ref{DATE_AND_TIME}, @gol
4736@ref{GMTIME}, @gol
4737@ref{LTIME}, @gol
4738@ref{TIME}, @gol
4739@ref{TIME8}
4740@end table
4741
4742
4743
4744@node DATE_AND_TIME
4745@section @code{DATE_AND_TIME} --- Date and time subroutine
4746@fnindex DATE_AND_TIME
4747@cindex date, current
4748@cindex current date
4749@cindex time, current
4750@cindex current time
4751
4752@table @asis
4753@item @emph{Description}:
4754@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4755time information from the real-time system clock.  @var{DATE} is
4756@code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
4757has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4758representing the difference with respect to Coordinated Universal Time (UTC).
4759Unavailable time and date parameters return blanks.
4760
4761@var{VALUES} is @code{INTENT(OUT)} and provides the following:
4762
4763@multitable @columnfractions .15 .70
4764@item @code{VALUE(1)}: @tab The year
4765@item @code{VALUE(2)}: @tab The month
4766@item @code{VALUE(3)}: @tab The day of the month
4767@item @code{VALUE(4)}: @tab Time difference with UTC in minutes
4768@item @code{VALUE(5)}: @tab The hour of the day
4769@item @code{VALUE(6)}: @tab The minutes of the hour
4770@item @code{VALUE(7)}: @tab The seconds of the minute
4771@item @code{VALUE(8)}: @tab The milliseconds of the second
4772@end multitable
4773
4774@item @emph{Standard}:
4775Fortran 90 and later
4776
4777@item @emph{Class}:
4778Subroutine
4779
4780@item @emph{Syntax}:
4781@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4782
4783@item @emph{Arguments}:
4784@multitable @columnfractions .15 .70
4785@item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4786or larger, and of default kind.
4787@item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4788or larger, and of default kind.
4789@item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4790or larger, and of default kind.
4791@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4792@end multitable
4793
4794@item @emph{Return value}:
4795None
4796
4797@item @emph{Example}:
4798@smallexample
4799program test_time_and_date
4800    character(8)  :: date
4801    character(10) :: time
4802    character(5)  :: zone
4803    integer,dimension(8) :: values
4804    ! using keyword arguments
4805    call date_and_time(date,time,zone,values)
4806    call date_and_time(DATE=date,ZONE=zone)
4807    call date_and_time(TIME=time)
4808    call date_and_time(VALUES=values)
4809    print '(a,2x,a,2x,a)', date, time, zone
4810    print '(8i5)', values
4811end program test_time_and_date
4812@end smallexample
4813
4814@item @emph{See also}:
4815@ref{CPU_TIME}, @gol
4816@ref{SYSTEM_CLOCK}
4817@end table
4818
4819
4820
4821@node DBLE
4822@section @code{DBLE} --- Double conversion function
4823@fnindex DBLE
4824@cindex conversion, to real
4825
4826@table @asis
4827@item @emph{Description}:
4828@code{DBLE(A)} Converts @var{A} to double precision real type.
4829
4830@item @emph{Standard}:
4831Fortran 77 and later
4832
4833@item @emph{Class}:
4834Elemental function
4835
4836@item @emph{Syntax}:
4837@code{RESULT = DBLE(A)}
4838
4839@item @emph{Arguments}:
4840@multitable @columnfractions .15 .70
4841@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4842or @code{COMPLEX}.
4843@end multitable
4844
4845@item @emph{Return value}:
4846The return value is of type double precision real.
4847
4848@item @emph{Example}:
4849@smallexample
4850program test_dble
4851    real    :: x = 2.18
4852    integer :: i = 5
4853    complex :: z = (2.3,1.14)
4854    print *, dble(x), dble(i), dble(z)
4855end program test_dble
4856@end smallexample
4857
4858@item @emph{See also}:
4859@ref{REAL}
4860@end table
4861
4862
4863
4864@node DCMPLX
4865@section @code{DCMPLX} --- Double complex conversion function
4866@fnindex DCMPLX
4867@cindex complex numbers, conversion to
4868@cindex conversion, to complex
4869
4870@table @asis
4871@item @emph{Description}:
4872@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4873converted to the real component.  If @var{Y} is present it is converted to the
4874imaginary component.  If @var{Y} is not present then the imaginary component is
4875set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
4876
4877@item @emph{Standard}:
4878GNU extension
4879
4880@item @emph{Class}:
4881Elemental function
4882
4883@item @emph{Syntax}:
4884@code{RESULT = DCMPLX(X [, Y])}
4885
4886@item @emph{Arguments}:
4887@multitable @columnfractions .15 .70
4888@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4889or @code{COMPLEX}.
4890@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4891@code{INTEGER} or @code{REAL}.
4892@end multitable
4893
4894@item @emph{Return value}:
4895The return value is of type @code{COMPLEX(8)}
4896
4897@item @emph{Example}:
4898@smallexample
4899program test_dcmplx
4900    integer :: i = 42
4901    real :: x = 3.14
4902    complex :: z
4903    z = cmplx(i, x)
4904    print *, dcmplx(i)
4905    print *, dcmplx(x)
4906    print *, dcmplx(z)
4907    print *, dcmplx(x,i)
4908end program test_dcmplx
4909@end smallexample
4910@end table
4911
4912
4913@node DIGITS
4914@section @code{DIGITS} --- Significant binary digits function
4915@fnindex DIGITS
4916@cindex model representation, significant digits
4917
4918@table @asis
4919@item @emph{Description}:
4920@code{DIGITS(X)} returns the number of significant binary digits of the internal
4921model representation of @var{X}.  For example, on a system using a 32-bit
4922floating point representation, a default real number would likely return 24.
4923
4924@item @emph{Standard}:
4925Fortran 90 and later
4926
4927@item @emph{Class}:
4928Inquiry function
4929
4930@item @emph{Syntax}:
4931@code{RESULT = DIGITS(X)}
4932
4933@item @emph{Arguments}:
4934@multitable @columnfractions .15 .70
4935@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4936@end multitable
4937
4938@item @emph{Return value}:
4939The return value is of type @code{INTEGER}.
4940
4941@item @emph{Example}:
4942@smallexample
4943program test_digits
4944    integer :: i = 12345
4945    real :: x = 3.143
4946    real(8) :: y = 2.33
4947    print *, digits(i)
4948    print *, digits(x)
4949    print *, digits(y)
4950end program test_digits
4951@end smallexample
4952@end table
4953
4954
4955
4956@node DIM
4957@section @code{DIM} --- Positive difference
4958@fnindex DIM
4959@fnindex IDIM
4960@fnindex DDIM
4961@cindex positive difference
4962
4963@table @asis
4964@item @emph{Description}:
4965@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4966otherwise returns zero.
4967
4968@item @emph{Standard}:
4969Fortran 77 and later
4970
4971@item @emph{Class}:
4972Elemental function
4973
4974@item @emph{Syntax}:
4975@code{RESULT = DIM(X, Y)}
4976
4977@item @emph{Arguments}:
4978@multitable @columnfractions .15 .70
4979@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4980@item @var{Y} @tab The type shall be the same type and kind as @var{X}.  (As
4981a GNU extension, arguments of different kinds are permitted.)
4982@end multitable
4983
4984@item @emph{Return value}:
4985The return value is of type @code{INTEGER} or @code{REAL}.  (As a GNU
4986extension, kind is the largest kind of the actual arguments.)
4987
4988@item @emph{Example}:
4989@smallexample
4990program test_dim
4991    integer :: i
4992    real(8) :: x
4993    i = dim(4, 15)
4994    x = dim(4.345_8, 2.111_8)
4995    print *, i
4996    print *, x
4997end program test_dim
4998@end smallexample
4999
5000@item @emph{Specific names}:
5001@multitable @columnfractions .20 .26 .20 .30
5002@headitem Name             @tab Argument               @tab Return type       @tab Standard
5003@item @code{DIM(X,Y)}  @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
5004@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5005@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
5006@end multitable
5007@end table
5008
5009
5010
5011@node DOT_PRODUCT
5012@section @code{DOT_PRODUCT} --- Dot product function
5013@fnindex DOT_PRODUCT
5014@cindex dot product
5015@cindex vector product
5016@cindex product, vector
5017
5018@table @asis
5019@item @emph{Description}:
5020@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
5021of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
5022either numeric or logical and must be arrays of rank one and of equal size. If
5023the vectors are @code{INTEGER} or @code{REAL}, the result is
5024@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
5025is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
5026the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
5027
5028@item @emph{Standard}:
5029Fortran 90 and later
5030
5031@item @emph{Class}:
5032Transformational function
5033
5034@item @emph{Syntax}:
5035@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
5036
5037@item @emph{Arguments}:
5038@multitable @columnfractions .15 .70
5039@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
5040@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.
5041@end multitable
5042
5043@item @emph{Return value}:
5044If the arguments are numeric, the return value is a scalar of numeric type,
5045@code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
5046@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
5047
5048@item @emph{Example}:
5049@smallexample
5050program test_dot_prod
5051    integer, dimension(3) :: a, b
5052    a = (/ 1, 2, 3 /)
5053    b = (/ 4, 5, 6 /)
5054    print '(3i3)', a
5055    print *
5056    print '(3i3)', b
5057    print *
5058    print *, dot_product(a,b)
5059end program test_dot_prod
5060@end smallexample
5061@end table
5062
5063
5064
5065@node DPROD
5066@section @code{DPROD} --- Double product function
5067@fnindex DPROD
5068@cindex product, double-precision
5069
5070@table @asis
5071@item @emph{Description}:
5072@code{DPROD(X,Y)} returns the product @code{X*Y}.
5073
5074@item @emph{Standard}:
5075Fortran 77 and later
5076
5077@item @emph{Class}:
5078Elemental function
5079
5080@item @emph{Syntax}:
5081@code{RESULT = DPROD(X, Y)}
5082
5083@item @emph{Arguments}:
5084@multitable @columnfractions .15 .70
5085@item @var{X} @tab The type shall be @code{REAL}.
5086@item @var{Y} @tab The type shall be @code{REAL}.
5087@end multitable
5088
5089@item @emph{Return value}:
5090The return value is of type @code{REAL(8)}.
5091
5092@item @emph{Example}:
5093@smallexample
5094program test_dprod
5095    real :: x = 5.2
5096    real :: y = 2.3
5097    real(8) :: d
5098    d = dprod(x,y)
5099    print *, d
5100end program test_dprod
5101@end smallexample
5102
5103@item @emph{Specific names}:
5104@multitable @columnfractions .20 .23 .20 .33
5105@headitem Name              @tab Argument               @tab Return type       @tab Standard
5106@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
5107@end multitable
5108
5109@end table
5110
5111
5112@node DREAL
5113@section @code{DREAL} --- Double real part function
5114@fnindex DREAL
5115@cindex complex numbers, real part
5116
5117@table @asis
5118@item @emph{Description}:
5119@code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5120
5121@item @emph{Standard}:
5122GNU extension
5123
5124@item @emph{Class}:
5125Elemental function
5126
5127@item @emph{Syntax}:
5128@code{RESULT = DREAL(A)}
5129
5130@item @emph{Arguments}:
5131@multitable @columnfractions .15 .70
5132@item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5133@end multitable
5134
5135@item @emph{Return value}:
5136The return value is of type @code{REAL(8)}.
5137
5138@item @emph{Example}:
5139@smallexample
5140program test_dreal
5141    complex(8) :: z = (1.3_8,7.2_8)
5142    print *, dreal(z)
5143end program test_dreal
5144@end smallexample
5145
5146@item @emph{See also}:
5147@ref{AIMAG}
5148
5149@end table
5150
5151
5152
5153@node DSHIFTL
5154@section @code{DSHIFTL} --- Combined left shift
5155@fnindex DSHIFTL
5156@cindex left shift, combined
5157@cindex shift, left
5158
5159@table @asis
5160@item @emph{Description}:
5161@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5162rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5163bits of @var{J}, and the remaining bits are the rightmost bits of
5164@var{I}.
5165
5166@item @emph{Standard}:
5167Fortran 2008 and later
5168
5169@item @emph{Class}:
5170Elemental function
5171
5172@item @emph{Syntax}:
5173@code{RESULT = DSHIFTL(I, J, SHIFT)}
5174
5175@item @emph{Arguments}:
5176@multitable @columnfractions .15 .70
5177@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5178@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5179If both @var{I} and @var{J} have integer type, then they shall have
5180the same kind type parameter. @var{I} and @var{J} shall not both be
5181BOZ constants.
5182@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5183be nonnegative.  If @var{I} is not a BOZ constant, then @var{SHIFT}
5184shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5185@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5186@end multitable
5187
5188@item @emph{Return value}:
5189If either @var{I} or @var{J} is a BOZ constant, it is first converted
5190as if by the intrinsic function @code{INT} to an integer type with the
5191kind type parameter of the other.
5192
5193@item @emph{See also}:
5194@ref{DSHIFTR}
5195@end table
5196
5197
5198@node DSHIFTR
5199@section @code{DSHIFTR} --- Combined right shift
5200@fnindex DSHIFTR
5201@cindex right shift, combined
5202@cindex shift, right
5203
5204@table @asis
5205@item @emph{Description}:
5206@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5207leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5208bits of @var{I}, and the remaining bits are the leftmost bits of
5209@var{J}.
5210
5211@item @emph{Standard}:
5212Fortran 2008 and later
5213
5214@item @emph{Class}:
5215Elemental function
5216
5217@item @emph{Syntax}:
5218@code{RESULT = DSHIFTR(I, J, SHIFT)}
5219
5220@item @emph{Arguments}:
5221@multitable @columnfractions .15 .70
5222@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5223@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5224If both @var{I} and @var{J} have integer type, then they shall have
5225the same kind type parameter. @var{I} and @var{J} shall not both be
5226BOZ constants.
5227@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5228be nonnegative.  If @var{I} is not a BOZ constant, then @var{SHIFT}
5229shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5230@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5231@end multitable
5232
5233@item @emph{Return value}:
5234If either @var{I} or @var{J} is a BOZ constant, it is first converted
5235as if by the intrinsic function @code{INT} to an integer type with the
5236kind type parameter of the other.
5237
5238@item @emph{See also}:
5239@ref{DSHIFTL}
5240@end table
5241
5242
5243@node DTIME
5244@section @code{DTIME} --- Execution time subroutine (or function)
5245@fnindex DTIME
5246@cindex time, elapsed
5247@cindex elapsed time
5248
5249@table @asis
5250@item @emph{Description}:
5251@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5252since the start of the process's execution in @var{TIME}.  @var{VALUES}
5253returns the user and system components of this time in @code{VALUES(1)} and
5254@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5255VALUES(2)}.
5256
5257Subsequent invocations of @code{DTIME} return values accumulated since the
5258previous invocation.
5259
5260On some systems, the underlying timings are represented using types with
5261sufficiently small limits that overflows (wrap around) are possible, such as
526232-bit types. Therefore, the values returned by this intrinsic might be, or
5263become, negative, or numerically less than previous values, during a single
5264run of the compiled program.
5265
5266Please note, that this implementation is thread safe if used within OpenMP
5267directives, i.e., its state will be consistent while called from multiple
5268threads. However, if @code{DTIME} is called from multiple threads, the result
5269is still the time since the last invocation. This may not give the intended
5270results. If possible, use @code{CPU_TIME} instead.
5271
5272This intrinsic is provided in both subroutine and function forms; however,
5273only one form can be used in any given program unit.
5274
5275@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5276
5277@multitable @columnfractions .15 .70
5278@item @code{VALUES(1)}: @tab User time in seconds.
5279@item @code{VALUES(2)}: @tab System time in seconds.
5280@item @code{TIME}: @tab Run time since start in seconds.
5281@end multitable
5282
5283@item @emph{Standard}:
5284GNU extension
5285
5286@item @emph{Class}:
5287Subroutine, function
5288
5289@item @emph{Syntax}:
5290@multitable @columnfractions .80
5291@item @code{CALL DTIME(VALUES, TIME)}.
5292@item @code{TIME = DTIME(VALUES)}, (not recommended).
5293@end multitable
5294
5295@item @emph{Arguments}:
5296@multitable @columnfractions .15 .70
5297@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5298@item @var{TIME}@tab The type shall be @code{REAL(4)}.
5299@end multitable
5300
5301@item @emph{Return value}:
5302Elapsed time in seconds since the last invocation or since the start of program
5303execution if not called before.
5304
5305@item @emph{Example}:
5306@smallexample
5307program test_dtime
5308    integer(8) :: i, j
5309    real, dimension(2) :: tarray
5310    real :: result
5311    call dtime(tarray, result)
5312    print *, result
5313    print *, tarray(1)
5314    print *, tarray(2)
5315    do i=1,100000000    ! Just a delay
5316        j = i * i - i
5317    end do
5318    call dtime(tarray, result)
5319    print *, result
5320    print *, tarray(1)
5321    print *, tarray(2)
5322end program test_dtime
5323@end smallexample
5324
5325@item @emph{See also}:
5326@ref{CPU_TIME}
5327
5328@end table
5329
5330
5331
5332@node EOSHIFT
5333@section @code{EOSHIFT} --- End-off shift elements of an array
5334@fnindex EOSHIFT
5335@cindex array, shift
5336
5337@table @asis
5338@item @emph{Description}:
5339@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5340elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
5341omitted it is taken to be @code{1}.  @var{DIM} is a scalar of type
5342@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5343rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
5344@var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
5345then all complete rank one sections of @var{ARRAY} along the given dimension are
5346shifted.  Elements shifted out one end of each rank one section are dropped.  If
5347@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5348is copied back in the other end.  If @var{BOUNDARY} is not present then the
5349following are copied in depending on the type of @var{ARRAY}.
5350
5351@multitable @columnfractions .15 .80
5352@item @emph{Array Type} @tab @emph{Boundary Value}
5353@item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
5354@item Logical  @tab @code{.FALSE.}.
5355@item Character(@var{len}) @tab @var{len} blanks.
5356@end multitable
5357
5358@item @emph{Standard}:
5359Fortran 90 and later
5360
5361@item @emph{Class}:
5362Transformational function
5363
5364@item @emph{Syntax}:
5365@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5366
5367@item @emph{Arguments}:
5368@multitable @columnfractions .15 .70
5369@item @var{ARRAY}  @tab May be any type, not scalar.
5370@item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
5371@item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5372@item @var{DIM}    @tab The type shall be @code{INTEGER}.
5373@end multitable
5374
5375@item @emph{Return value}:
5376Returns an array of same type and rank as the @var{ARRAY} argument.
5377
5378@item @emph{Example}:
5379@smallexample
5380program test_eoshift
5381    integer, dimension(3,3) :: a
5382    a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5383    print '(3i3)', a(1,:)
5384    print '(3i3)', a(2,:)
5385    print '(3i3)', a(3,:)
5386    a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5387    print *
5388    print '(3i3)', a(1,:)
5389    print '(3i3)', a(2,:)
5390    print '(3i3)', a(3,:)
5391end program test_eoshift
5392@end smallexample
5393@end table
5394
5395
5396
5397@node EPSILON
5398@section @code{EPSILON} --- Epsilon function
5399@fnindex EPSILON
5400@cindex model representation, epsilon
5401
5402@table @asis
5403@item @emph{Description}:
5404@code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5405as @var{X} such that @math{1 + E > 1}.
5406
5407@item @emph{Standard}:
5408Fortran 90 and later
5409
5410@item @emph{Class}:
5411Inquiry function
5412
5413@item @emph{Syntax}:
5414@code{RESULT = EPSILON(X)}
5415
5416@item @emph{Arguments}:
5417@multitable @columnfractions .15 .70
5418@item @var{X} @tab The type shall be @code{REAL}.
5419@end multitable
5420
5421@item @emph{Return value}:
5422The return value is of same type as the argument.
5423
5424@item @emph{Example}:
5425@smallexample
5426program test_epsilon
5427    real :: x = 3.143
5428    real(8) :: y = 2.33
5429    print *, EPSILON(x)
5430    print *, EPSILON(y)
5431end program test_epsilon
5432@end smallexample
5433@end table
5434
5435
5436
5437@node ERF
5438@section @code{ERF} --- Error function
5439@fnindex ERF
5440@cindex error function
5441
5442@table @asis
5443@item @emph{Description}:
5444@code{ERF(X)} computes the error function of @var{X}.
5445
5446@item @emph{Standard}:
5447Fortran 2008 and later
5448
5449@item @emph{Class}:
5450Elemental function
5451
5452@item @emph{Syntax}:
5453@code{RESULT = ERF(X)}
5454
5455@item @emph{Arguments}:
5456@multitable @columnfractions .15 .70
5457@item @var{X} @tab The type shall be @code{REAL}.
5458@end multitable
5459
5460@item @emph{Return value}:
5461The return value is of type @code{REAL}, of the same kind as
5462@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5463
5464@item @emph{Example}:
5465@smallexample
5466program test_erf
5467  real(8) :: x = 0.17_8
5468  x = erf(x)
5469end program test_erf
5470@end smallexample
5471
5472@item @emph{Specific names}:
5473@multitable @columnfractions .20 .23 .20 .33
5474@headitem Name            @tab Argument          @tab Return type       @tab Standard
5475@item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
5476@end multitable
5477@end table
5478
5479
5480
5481@node ERFC
5482@section @code{ERFC} --- Error function
5483@fnindex ERFC
5484@cindex error function, complementary
5485
5486@table @asis
5487@item @emph{Description}:
5488@code{ERFC(X)} computes the complementary error function of @var{X}.
5489
5490@item @emph{Standard}:
5491Fortran 2008 and later
5492
5493@item @emph{Class}:
5494Elemental function
5495
5496@item @emph{Syntax}:
5497@code{RESULT = ERFC(X)}
5498
5499@item @emph{Arguments}:
5500@multitable @columnfractions .15 .70
5501@item @var{X} @tab The type shall be @code{REAL}.
5502@end multitable
5503
5504@item @emph{Return value}:
5505The return value is of type @code{REAL} and of the same kind as @var{X}.
5506It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5507
5508@item @emph{Example}:
5509@smallexample
5510program test_erfc
5511  real(8) :: x = 0.17_8
5512  x = erfc(x)
5513end program test_erfc
5514@end smallexample
5515
5516@item @emph{Specific names}:
5517@multitable @columnfractions .20 .23 .20 .33
5518@headitem Name            @tab Argument          @tab Return type       @tab Standard
5519@item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
5520@end multitable
5521@end table
5522
5523
5524
5525@node ERFC_SCALED
5526@section @code{ERFC_SCALED} --- Error function
5527@fnindex ERFC_SCALED
5528@cindex error function, complementary, exponentially-scaled
5529
5530@table @asis
5531@item @emph{Description}:
5532@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5533error function of @var{X}.
5534
5535@item @emph{Standard}:
5536Fortran 2008 and later
5537
5538@item @emph{Class}:
5539Elemental function
5540
5541@item @emph{Syntax}:
5542@code{RESULT = ERFC_SCALED(X)}
5543
5544@item @emph{Arguments}:
5545@multitable @columnfractions .15 .70
5546@item @var{X} @tab The type shall be @code{REAL}.
5547@end multitable
5548
5549@item @emph{Return value}:
5550The return value is of type @code{REAL} and of the same kind as @var{X}.
5551
5552@item @emph{Example}:
5553@smallexample
5554program test_erfc_scaled
5555  real(8) :: x = 0.17_8
5556  x = erfc_scaled(x)
5557end program test_erfc_scaled
5558@end smallexample
5559@end table
5560
5561
5562
5563@node ETIME
5564@section @code{ETIME} --- Execution time subroutine (or function)
5565@fnindex ETIME
5566@cindex time, elapsed
5567
5568@table @asis
5569@item @emph{Description}:
5570@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5571since the start of the process's execution in @var{TIME}.  @var{VALUES}
5572returns the user and system components of this time in @code{VALUES(1)} and
5573@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5574
5575On some systems, the underlying timings are represented using types with
5576sufficiently small limits that overflows (wrap around) are possible, such as
557732-bit types. Therefore, the values returned by this intrinsic might be, or
5578become, negative, or numerically less than previous values, during a single
5579run of the compiled program.
5580
5581This intrinsic is provided in both subroutine and function forms; however,
5582only one form can be used in any given program unit.
5583
5584@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5585
5586@multitable @columnfractions .15 .70
5587@item @code{VALUES(1)}: @tab User time in seconds.
5588@item @code{VALUES(2)}: @tab System time in seconds.
5589@item @code{TIME}: @tab Run time since start in seconds.
5590@end multitable
5591
5592@item @emph{Standard}:
5593GNU extension
5594
5595@item @emph{Class}:
5596Subroutine, function
5597
5598@item @emph{Syntax}:
5599@multitable @columnfractions .80
5600@item @code{CALL ETIME(VALUES, TIME)}.
5601@item @code{TIME = ETIME(VALUES)}, (not recommended).
5602@end multitable
5603
5604@item @emph{Arguments}:
5605@multitable @columnfractions .15 .70
5606@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5607@item @var{TIME}@tab The type shall be @code{REAL(4)}.
5608@end multitable
5609
5610@item @emph{Return value}:
5611Elapsed time in seconds since the start of program execution.
5612
5613@item @emph{Example}:
5614@smallexample
5615program test_etime
5616    integer(8) :: i, j
5617    real, dimension(2) :: tarray
5618    real :: result
5619    call ETIME(tarray, result)
5620    print *, result
5621    print *, tarray(1)
5622    print *, tarray(2)
5623    do i=1,100000000    ! Just a delay
5624        j = i * i - i
5625    end do
5626    call ETIME(tarray, result)
5627    print *, result
5628    print *, tarray(1)
5629    print *, tarray(2)
5630end program test_etime
5631@end smallexample
5632
5633@item @emph{See also}:
5634@ref{CPU_TIME}
5635
5636@end table
5637
5638
5639
5640@node EVENT_QUERY
5641@section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5642@fnindex EVENT_QUERY
5643@cindex Events, EVENT_QUERY
5644
5645@table @asis
5646@item @emph{Description}:
5647@code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5648posted to the @var{EVENT} variable and not yet been removed by calling
5649@code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
5650it is assigned the value 0. If it is present and the invocation has failed,
5651it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5652
5653@item @emph{Standard}:
5654TS 18508 or later
5655
5656@item @emph{Class}:
5657 subroutine
5658
5659@item @emph{Syntax}:
5660@code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5661
5662@item @emph{Arguments}:
5663@multitable @columnfractions .15 .70
5664@item @var{EVENT}  @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5665defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5666@item @var{COUNT}  @tab (intent(out))Scalar integer with at least the
5667precision of default integer.
5668@item @var{STAT}   @tab (optional) Scalar default-kind integer variable.
5669@end multitable
5670
5671@item @emph{Example}:
5672@smallexample
5673program atomic
5674  use iso_fortran_env
5675  implicit none
5676  type(event_type) :: event_value_has_been_set[*]
5677  integer :: cnt
5678  if (this_image() == 1) then
5679    call event_query (event_value_has_been_set, cnt)
5680    if (cnt > 0) write(*,*) "Value has been set"
5681  elseif (this_image() == 2) then
5682    event post (event_value_has_been_set[1])
5683  end if
5684end program atomic
5685@end smallexample
5686
5687@end table
5688
5689
5690
5691@node EXECUTE_COMMAND_LINE
5692@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5693@fnindex EXECUTE_COMMAND_LINE
5694@cindex system, system call
5695@cindex command line
5696
5697@table @asis
5698@item @emph{Description}:
5699@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5700asynchronously.
5701
5702The @code{COMMAND} argument is passed to the shell and executed (The
5703shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.).
5704If @code{WAIT} is present and has the value false, the execution of
5705the command is asynchronous if the system supports it; otherwise, the
5706command is executed synchronously using the C library's @code{system}
5707call.
5708
5709The three last arguments allow the user to get status information.  After
5710synchronous execution, @code{EXITSTAT} contains the integer exit code of
5711the command, as returned by @code{system}.  @code{CMDSTAT} is set to zero
5712if the command line was executed (whatever its exit status was).
5713@code{CMDMSG} is assigned an error message if an error has occurred.
5714
5715Note that the @code{system} function need not be thread-safe. It is
5716the responsibility of the user to ensure that @code{system} is not
5717called concurrently.
5718
5719For asynchronous execution on supported targets, the POSIX
5720@code{posix_spawn} or @code{fork} functions are used.  Also, a signal
5721handler for the @code{SIGCHLD} signal is installed.
5722
5723@item @emph{Standard}:
5724Fortran 2008 and later
5725
5726@item @emph{Class}:
5727Subroutine
5728
5729@item @emph{Syntax}:
5730@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5731
5732@item @emph{Arguments}:
5733@multitable @columnfractions .15 .70
5734@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5735@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5736@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5737default kind.
5738@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5739default kind.
5740@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5741default kind.
5742@end multitable
5743
5744@item @emph{Example}:
5745@smallexample
5746program test_exec
5747  integer :: i
5748
5749  call execute_command_line ("external_prog.exe", exitstat=i)
5750  print *, "Exit status of external_prog.exe was ", i
5751
5752  call execute_command_line ("reindex_files.exe", wait=.false.)
5753  print *, "Now reindexing files in the background"
5754
5755end program test_exec
5756@end smallexample
5757
5758
5759@item @emph{Note}:
5760
5761Because this intrinsic is implemented in terms of the @code{system}
5762function call, its behavior with respect to signaling is processor
5763dependent. In particular, on POSIX-compliant systems, the SIGINT and
5764SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5765such, if the parent process is terminated, the child process might not be
5766terminated alongside.
5767
5768
5769@item @emph{See also}:
5770@ref{SYSTEM}
5771@end table
5772
5773
5774
5775@node EXIT
5776@section @code{EXIT} --- Exit the program with status.
5777@fnindex EXIT
5778@cindex program termination
5779@cindex terminate program
5780
5781@table @asis
5782@item @emph{Description}:
5783@code{EXIT} causes immediate termination of the program with status.  If status
5784is omitted it returns the canonical @emph{success} for the system.  All Fortran
5785I/O units are closed.
5786
5787@item @emph{Standard}:
5788GNU extension
5789
5790@item @emph{Class}:
5791Subroutine
5792
5793@item @emph{Syntax}:
5794@code{CALL EXIT([STATUS])}
5795
5796@item @emph{Arguments}:
5797@multitable @columnfractions .15 .70
5798@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5799@end multitable
5800
5801@item @emph{Return value}:
5802@code{STATUS} is passed to the parent process on exit.
5803
5804@item @emph{Example}:
5805@smallexample
5806program test_exit
5807  integer :: STATUS = 0
5808  print *, 'This program is going to exit.'
5809  call EXIT(STATUS)
5810end program test_exit
5811@end smallexample
5812
5813@item @emph{See also}:
5814@ref{ABORT}, @gol
5815@ref{KILL}
5816@end table
5817
5818
5819
5820@node EXP
5821@section @code{EXP} --- Exponential function
5822@fnindex EXP
5823@fnindex DEXP
5824@fnindex CEXP
5825@fnindex ZEXP
5826@fnindex CDEXP
5827@cindex exponential function
5828@cindex logarithm function, inverse
5829
5830@table @asis
5831@item @emph{Description}:
5832@code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5833
5834@item @emph{Standard}:
5835Fortran 77 and later, has overloads that are GNU extensions
5836
5837@item @emph{Class}:
5838Elemental function
5839
5840@item @emph{Syntax}:
5841@code{RESULT = EXP(X)}
5842
5843@item @emph{Arguments}:
5844@multitable @columnfractions .15 .70
5845@item @var{X} @tab The type shall be @code{REAL} or
5846@code{COMPLEX}.
5847@end multitable
5848
5849@item @emph{Return value}:
5850The return value has same type and kind as @var{X}.
5851
5852@item @emph{Example}:
5853@smallexample
5854program test_exp
5855  real :: x = 1.0
5856  x = exp(x)
5857end program test_exp
5858@end smallexample
5859
5860@item @emph{Specific names}:
5861@multitable @columnfractions .20 .23 .20 .33
5862@headitem Name            @tab Argument             @tab Return type         @tab Standard
5863@item @code{EXP(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}      @tab Fortran 77 and later
5864@item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
5865@item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
5866@item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
5867@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
5868@end multitable
5869@end table
5870
5871
5872
5873@node EXPONENT
5874@section @code{EXPONENT} --- Exponent function
5875@fnindex EXPONENT
5876@cindex real number, exponent
5877@cindex floating point, exponent
5878
5879@table @asis
5880@item @emph{Description}:
5881@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5882is zero the value returned is zero.
5883
5884@item @emph{Standard}:
5885Fortran 90 and later
5886
5887@item @emph{Class}:
5888Elemental function
5889
5890@item @emph{Syntax}:
5891@code{RESULT = EXPONENT(X)}
5892
5893@item @emph{Arguments}:
5894@multitable @columnfractions .15 .70
5895@item @var{X} @tab The type shall be @code{REAL}.
5896@end multitable
5897
5898@item @emph{Return value}:
5899The return value is of type default @code{INTEGER}.
5900
5901@item @emph{Example}:
5902@smallexample
5903program test_exponent
5904  real :: x = 1.0
5905  integer :: i
5906  i = exponent(x)
5907  print *, i
5908  print *, exponent(0.0)
5909end program test_exponent
5910@end smallexample
5911@end table
5912
5913
5914
5915@node EXTENDS_TYPE_OF
5916@section @code{EXTENDS_TYPE_OF} ---  Query dynamic type for extension
5917@fnindex EXTENDS_TYPE_OF
5918
5919@table @asis
5920@item @emph{Description}:
5921Query dynamic type for extension.
5922
5923@item @emph{Standard}:
5924Fortran 2003 and later
5925
5926@item @emph{Class}:
5927Inquiry function
5928
5929@item @emph{Syntax}:
5930@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5931
5932@item @emph{Arguments}:
5933@multitable @columnfractions .15 .70
5934@item @var{A} @tab Shall be an object of extensible declared type or
5935unlimited polymorphic.
5936@item @var{MOLD} @tab Shall be an object of extensible declared type or
5937unlimited polymorphic.
5938@end multitable
5939
5940@item @emph{Return value}:
5941The return value is a scalar of type default logical. It is true if and only if
5942the dynamic type of A is an extension type of the dynamic type of MOLD.
5943
5944
5945@item @emph{See also}:
5946@ref{SAME_TYPE_AS}
5947@end table
5948
5949
5950
5951@node FDATE
5952@section @code{FDATE} --- Get the current time as a string
5953@fnindex FDATE
5954@cindex time, current
5955@cindex current time
5956@cindex date, current
5957@cindex current date
5958
5959@table @asis
5960@item @emph{Description}:
5961@code{FDATE(DATE)} returns the current date (using the same format as
5962@ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5963TIME())}.
5964
5965This intrinsic is provided in both subroutine and function forms; however,
5966only one form can be used in any given program unit.
5967
5968@item @emph{Standard}:
5969GNU extension
5970
5971@item @emph{Class}:
5972Subroutine, function
5973
5974@item @emph{Syntax}:
5975@multitable @columnfractions .80
5976@item @code{CALL FDATE(DATE)}.
5977@item @code{DATE = FDATE()}.
5978@end multitable
5979
5980@item @emph{Arguments}:
5981@multitable @columnfractions .15 .70
5982@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5983default kind. It is an @code{INTENT(OUT)} argument.  If the length of
5984this variable is too short for the date and time string to fit
5985completely, it will be blank on procedure return.
5986@end multitable
5987
5988@item @emph{Return value}:
5989The current date and time as a string.
5990
5991@item @emph{Example}:
5992@smallexample
5993program test_fdate
5994    integer(8) :: i, j
5995    character(len=30) :: date
5996    call fdate(date)
5997    print *, 'Program started on ', date
5998    do i = 1, 100000000 ! Just a delay
5999        j = i * i - i
6000    end do
6001    call fdate(date)
6002    print *, 'Program ended on ', date
6003end program test_fdate
6004@end smallexample
6005
6006@item @emph{See also}:
6007@ref{DATE_AND_TIME}, @gol
6008@ref{CTIME}
6009@end table
6010
6011
6012@node FGET
6013@section @code{FGET} --- Read a single character in stream mode from stdin
6014@fnindex FGET
6015@cindex read character, stream mode
6016@cindex stream mode, read character
6017@cindex file operation, read character
6018
6019@table @asis
6020@item @emph{Description}:
6021Read a single character in stream mode from stdin by bypassing normal
6022formatted output. Stream I/O should not be mixed with normal record-oriented
6023(formatted or unformatted) I/O on the same unit; the results are unpredictable.
6024
6025This intrinsic is provided in both subroutine and function forms; however,
6026only one form can be used in any given program unit.
6027
6028Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6029@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
6030Programmers should consider the use of new stream IO feature in new code
6031for future portability. See also @ref{Fortran 2003 status}.
6032
6033@item @emph{Standard}:
6034GNU extension
6035
6036@item @emph{Class}:
6037Subroutine, function
6038
6039@item @emph{Syntax}:
6040@multitable @columnfractions .80
6041@item @code{CALL FGET(C [, STATUS])}
6042@item @code{STATUS = FGET(C)}
6043@end multitable
6044
6045@item @emph{Arguments}:
6046@multitable @columnfractions .15 .70
6047@item @var{C}      @tab The type shall be @code{CHARACTER} and of default
6048kind.
6049@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6050Returns 0 on success, -1 on end-of-file, and a system specific positive
6051error code otherwise.
6052@end multitable
6053
6054@item @emph{Example}:
6055@smallexample
6056PROGRAM test_fget
6057  INTEGER, PARAMETER :: strlen = 100
6058  INTEGER :: status, i = 1
6059  CHARACTER(len=strlen) :: str = ""
6060
6061  WRITE (*,*) 'Enter text:'
6062  DO
6063    CALL fget(str(i:i), status)
6064    if (status /= 0 .OR. i > strlen) exit
6065    i = i + 1
6066  END DO
6067  WRITE (*,*) TRIM(str)
6068END PROGRAM
6069@end smallexample
6070
6071@item @emph{See also}:
6072@ref{FGETC}, @gol
6073@ref{FPUT}, @gol
6074@ref{FPUTC}
6075@end table
6076
6077
6078
6079@node FGETC
6080@section @code{FGETC} --- Read a single character in stream mode
6081@fnindex FGETC
6082@cindex read character, stream mode
6083@cindex stream mode, read character
6084@cindex file operation, read character
6085
6086@table @asis
6087@item @emph{Description}:
6088Read a single character in stream mode by bypassing normal formatted output.
6089Stream I/O should not be mixed with normal record-oriented (formatted or
6090unformatted) I/O on the same unit; the results are unpredictable.
6091
6092This intrinsic is provided in both subroutine and function forms; however,
6093only one form can be used in any given program unit.
6094
6095Note that the @code{FGET} intrinsic is provided for backwards compatibility
6096with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
6097Programmers should consider the use of new stream IO feature in new code
6098for future portability. See also @ref{Fortran 2003 status}.
6099
6100@item @emph{Standard}:
6101GNU extension
6102
6103@item @emph{Class}:
6104Subroutine, function
6105
6106@item @emph{Syntax}:
6107@multitable @columnfractions .80
6108@item @code{CALL FGETC(UNIT, C [, STATUS])}
6109@item @code{STATUS = FGETC(UNIT, C)}
6110@end multitable
6111
6112@item @emph{Arguments}:
6113@multitable @columnfractions .15 .70
6114@item @var{UNIT}   @tab The type shall be @code{INTEGER}.
6115@item @var{C}      @tab The type shall be @code{CHARACTER} and of default
6116kind.
6117@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6118Returns 0 on success, -1 on end-of-file and a system specific positive
6119error code otherwise.
6120@end multitable
6121
6122@item @emph{Example}:
6123@smallexample
6124PROGRAM test_fgetc
6125  INTEGER :: fd = 42, status
6126  CHARACTER :: c
6127
6128  OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6129  DO
6130    CALL fgetc(fd, c, status)
6131    IF (status /= 0) EXIT
6132    call fput(c)
6133  END DO
6134  CLOSE(UNIT=fd)
6135END PROGRAM
6136@end smallexample
6137
6138@item @emph{See also}:
6139@ref{FGET}, @gol
6140@ref{FPUT}, @gol
6141@ref{FPUTC}
6142@end table
6143
6144@node FINDLOC
6145@section @code{FINDLOC} --- Search an array for a value
6146@fnindex FINDLOC
6147@cindex findloc
6148
6149@table @asis
6150@item @emph{Description}:
6151Determines the location of the element in the array with the value
6152given in the @var{VALUE} argument, or, if the @var{DIM} argument is
6153supplied, determines the locations of the elements equal to the
6154@var{VALUE} argument element along each
6155row of the array in the @var{DIM} direction.  If @var{MASK} is
6156present, only the elements for which @var{MASK} is @code{.TRUE.} are
6157considered.  If more than one element in the array has the value
6158@var{VALUE}, the location returned is that of the first such element
6159in array element order if the @var{BACK} is not present or if it is
6160@code{.FALSE.}. If @var{BACK} is true, the location returned is that
6161of the last such element. If the array has zero size, or all of the
6162elements of @var{MASK} are @code{.FALSE.}, then the result is an array
6163of zeroes.  Similarly, if @var{DIM} is supplied and all of the
6164elements of @var{MASK} along a given row are zero, the result value
6165for that row is zero.
6166
6167@item @emph{Standard}:
6168Fortran 2008 and later.
6169
6170@item @emph{Class}:
6171Transformational function
6172
6173@item @emph{Syntax}:
6174@multitable @columnfractions .80
6175@item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])}
6176@item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])}
6177@end multitable
6178
6179@item @emph{Arguments}:
6180@multitable @columnfractions .15 .70
6181@item @var{ARRAY} @tab Shall be an array of intrinsic type.
6182@item @var{VALUE} @tab A scalar of intrinsic type which is in type
6183conformance with @var{ARRAY}.
6184@item @var{DIM} @tab (Optional) Shall be a scalar of type
6185@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
6186inclusive.  It may not be an optional dummy argument.
6187@item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL},
6188and conformable with @var{ARRAY}.
6189@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6190expression indicating the kind parameter of the result.
6191@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
6192@end multitable
6193
6194@item @emph{Return value}:
6195If @var{DIM} is absent, the result is a rank-one array with a length
6196equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
6197is an array with a rank one less than the rank of @var{ARRAY}, and a
6198size corresponding to the size of @var{ARRAY} with the @var{DIM}
6199dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
6200of one, the result is a scalar.  If the optional argument @var{KIND}
6201is present, the result is an integer of kind @var{KIND}, otherwise it
6202is of default kind.
6203
6204@item @emph{See also}:
6205@ref{MAXLOC}, @gol
6206@ref{MINLOC}
6207
6208@end table
6209
6210@node FLOOR
6211@section @code{FLOOR} --- Integer floor function
6212@fnindex FLOOR
6213@cindex floor
6214@cindex rounding, floor
6215
6216@table @asis
6217@item @emph{Description}:
6218@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
6219
6220@item @emph{Standard}:
6221Fortran 95 and later
6222
6223@item @emph{Class}:
6224Elemental function
6225
6226@item @emph{Syntax}:
6227@code{RESULT = FLOOR(A [, KIND])}
6228
6229@item @emph{Arguments}:
6230@multitable @columnfractions .15 .70
6231@item @var{A} @tab The type shall be @code{REAL}.
6232@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6233expression indicating the kind parameter of the result.
6234@end multitable
6235
6236@item @emph{Return value}:
6237The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6238and of default-kind @code{INTEGER} otherwise.
6239
6240@item @emph{Example}:
6241@smallexample
6242program test_floor
6243    real :: x = 63.29
6244    real :: y = -63.59
6245    print *, floor(x) ! returns 63
6246    print *, floor(y) ! returns -64
6247end program test_floor
6248@end smallexample
6249
6250@item @emph{See also}:
6251@ref{CEILING}, @gol
6252@ref{NINT}
6253@end table
6254
6255
6256
6257@node FLUSH
6258@section @code{FLUSH} --- Flush I/O unit(s)
6259@fnindex FLUSH
6260@cindex file operation, flush
6261
6262@table @asis
6263@item @emph{Description}:
6264Flushes Fortran unit(s) currently open for output. Without the optional
6265argument, all units are flushed, otherwise just the unit specified.
6266
6267@item @emph{Standard}:
6268GNU extension
6269
6270@item @emph{Class}:
6271Subroutine
6272
6273@item @emph{Syntax}:
6274@code{CALL FLUSH(UNIT)}
6275
6276@item @emph{Arguments}:
6277@multitable @columnfractions .15 .70
6278@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6279@end multitable
6280
6281@item @emph{Note}:
6282Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6283statement that should be preferred over the @code{FLUSH} intrinsic.
6284
6285The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6286have identical effect: they flush the runtime library's I/O buffer so
6287that the data becomes visible to other processes. This does not guarantee
6288that the data is committed to disk.
6289
6290On POSIX systems, you can request that all data is transferred  to  the
6291storage device by calling the @code{fsync} function, with the POSIX file
6292descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6293@code{FNUM}). The following example shows how:
6294
6295@smallexample
6296  ! Declare the interface for POSIX fsync function
6297  interface
6298    function fsync (fd) bind(c,name="fsync")
6299    use iso_c_binding, only: c_int
6300      integer(c_int), value :: fd
6301      integer(c_int) :: fsync
6302    end function fsync
6303  end interface
6304
6305  ! Variable declaration
6306  integer :: ret
6307
6308  ! Opening unit 10
6309  open (10,file="foo")
6310
6311  ! ...
6312  ! Perform I/O on unit 10
6313  ! ...
6314
6315  ! Flush and sync
6316  flush(10)
6317  ret = fsync(fnum(10))
6318
6319  ! Handle possible error
6320  if (ret /= 0) stop "Error calling FSYNC"
6321@end smallexample
6322
6323@end table
6324
6325
6326
6327@node FNUM
6328@section @code{FNUM} --- File number function
6329@fnindex FNUM
6330@cindex file operation, file number
6331
6332@table @asis
6333@item @emph{Description}:
6334@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6335open Fortran I/O unit @code{UNIT}.
6336
6337@item @emph{Standard}:
6338GNU extension
6339
6340@item @emph{Class}:
6341Function
6342
6343@item @emph{Syntax}:
6344@code{RESULT = FNUM(UNIT)}
6345
6346@item @emph{Arguments}:
6347@multitable @columnfractions .15 .70
6348@item @var{UNIT} @tab The type shall be @code{INTEGER}.
6349@end multitable
6350
6351@item @emph{Return value}:
6352The return value is of type @code{INTEGER}
6353
6354@item @emph{Example}:
6355@smallexample
6356program test_fnum
6357  integer :: i
6358  open (unit=10, status = "scratch")
6359  i = fnum(10)
6360  print *, i
6361  close (10)
6362end program test_fnum
6363@end smallexample
6364@end table
6365
6366
6367
6368@node FPUT
6369@section @code{FPUT} --- Write a single character in stream mode to stdout
6370@fnindex FPUT
6371@cindex write character, stream mode
6372@cindex stream mode, write character
6373@cindex file operation, write character
6374
6375@table @asis
6376@item @emph{Description}:
6377Write a single character in stream mode to stdout by bypassing normal
6378formatted output. Stream I/O should not be mixed with normal record-oriented
6379(formatted or unformatted) I/O on the same unit; the results are unpredictable.
6380
6381This intrinsic is provided in both subroutine and function forms; however,
6382only one form can be used in any given program unit.
6383
6384Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6385@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
6386Programmers should consider the use of new stream IO feature in new code
6387for future portability. See also @ref{Fortran 2003 status}.
6388
6389@item @emph{Standard}:
6390GNU extension
6391
6392@item @emph{Class}:
6393Subroutine, function
6394
6395@item @emph{Syntax}:
6396@multitable @columnfractions .80
6397@item @code{CALL FPUT(C [, STATUS])}
6398@item @code{STATUS = FPUT(C)}
6399@end multitable
6400
6401@item @emph{Arguments}:
6402@multitable @columnfractions .15 .70
6403@item @var{C}      @tab The type shall be @code{CHARACTER} and of default
6404kind.
6405@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6406Returns 0 on success, -1 on end-of-file and a system specific positive
6407error code otherwise.
6408@end multitable
6409
6410@item @emph{Example}:
6411@smallexample
6412PROGRAM test_fput
6413  CHARACTER(len=10) :: str = "gfortran"
6414  INTEGER :: i
6415  DO i = 1, len_trim(str)
6416    CALL fput(str(i:i))
6417  END DO
6418END PROGRAM
6419@end smallexample
6420
6421@item @emph{See also}:
6422@ref{FPUTC}, @gol
6423@ref{FGET}, @gol
6424@ref{FGETC}
6425@end table
6426
6427
6428
6429@node FPUTC
6430@section @code{FPUTC} --- Write a single character in stream mode
6431@fnindex FPUTC
6432@cindex write character, stream mode
6433@cindex stream mode, write character
6434@cindex file operation, write character
6435
6436@table @asis
6437@item @emph{Description}:
6438Write a single character in stream mode by bypassing normal formatted
6439output. Stream I/O should not be mixed with normal record-oriented
6440(formatted or unformatted) I/O on the same unit; the results are unpredictable.
6441
6442This intrinsic is provided in both subroutine and function forms; however,
6443only one form can be used in any given program unit.
6444
6445Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6446@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
6447Programmers should consider the use of new stream IO feature in new code
6448for future portability. See also @ref{Fortran 2003 status}.
6449
6450@item @emph{Standard}:
6451GNU extension
6452
6453@item @emph{Class}:
6454Subroutine, function
6455
6456@item @emph{Syntax}:
6457@multitable @columnfractions .80
6458@item @code{CALL FPUTC(UNIT, C [, STATUS])}
6459@item @code{STATUS = FPUTC(UNIT, C)}
6460@end multitable
6461
6462@item @emph{Arguments}:
6463@multitable @columnfractions .15 .70
6464@item @var{UNIT}   @tab The type shall be @code{INTEGER}.
6465@item @var{C}      @tab The type shall be @code{CHARACTER} and of default
6466kind.
6467@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6468Returns 0 on success, -1 on end-of-file and a system specific positive
6469error code otherwise.
6470@end multitable
6471
6472@item @emph{Example}:
6473@smallexample
6474PROGRAM test_fputc
6475  CHARACTER(len=10) :: str = "gfortran"
6476  INTEGER :: fd = 42, i
6477
6478  OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6479  DO i = 1, len_trim(str)
6480    CALL fputc(fd, str(i:i))
6481  END DO
6482  CLOSE(fd)
6483END PROGRAM
6484@end smallexample
6485
6486@item @emph{See also}:
6487@ref{FPUT}, @gol
6488@ref{FGET}, @gol
6489@ref{FGETC}
6490@end table
6491
6492
6493
6494@node FRACTION
6495@section @code{FRACTION} --- Fractional part of the model representation
6496@fnindex FRACTION
6497@cindex real number, fraction
6498@cindex floating point, fraction
6499
6500@table @asis
6501@item @emph{Description}:
6502@code{FRACTION(X)} returns the fractional part of the model
6503representation of @code{X}.
6504
6505@item @emph{Standard}:
6506Fortran 90 and later
6507
6508@item @emph{Class}:
6509Elemental function
6510
6511@item @emph{Syntax}:
6512@code{Y = FRACTION(X)}
6513
6514@item @emph{Arguments}:
6515@multitable @columnfractions .15 .70
6516@item @var{X} @tab The type of the argument shall be a @code{REAL}.
6517@end multitable
6518
6519@item @emph{Return value}:
6520The return value is of the same type and kind as the argument.
6521The fractional part of the model representation of @code{X} is returned;
6522it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6523
6524@item @emph{Example}:
6525@smallexample
6526program test_fraction
6527  real :: x
6528  x = 178.1387e-4
6529  print *, fraction(x), x * radix(x)**(-exponent(x))
6530end program test_fraction
6531@end smallexample
6532
6533@end table
6534
6535
6536
6537@node FREE
6538@section @code{FREE} --- Frees memory
6539@fnindex FREE
6540@cindex pointer, cray
6541
6542@table @asis
6543@item @emph{Description}:
6544Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6545intrinsic is an extension intended to be used with Cray pointers, and is
6546provided in GNU Fortran to allow user to compile legacy code. For
6547new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6548@code{DEALLOCATE}.
6549
6550@item @emph{Standard}:
6551GNU extension
6552
6553@item @emph{Class}:
6554Subroutine
6555
6556@item @emph{Syntax}:
6557@code{CALL FREE(PTR)}
6558
6559@item @emph{Arguments}:
6560@multitable @columnfractions .15 .70
6561@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6562location of the memory that should be de-allocated.
6563@end multitable
6564
6565@item @emph{Return value}:
6566None
6567
6568@item @emph{Example}:
6569See @code{MALLOC} for an example.
6570
6571@item @emph{See also}:
6572@ref{MALLOC}
6573@end table
6574
6575
6576
6577@node FSEEK
6578@section @code{FSEEK} --- Low level file positioning subroutine
6579@fnindex FSEEK
6580@cindex file operation, seek
6581@cindex file operation, position
6582
6583@table @asis
6584@item @emph{Description}:
6585Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6586is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6587if set to 1, @var{OFFSET} is taken to be relative to the current position
6588@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6589On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6590fails silently.
6591
6592This intrinsic routine is not fully backwards compatible with @command{g77}.
6593In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6594@var{STATUS} variable. If FSEEK is used in old code, change
6595@smallexample
6596  CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6597@end smallexample
6598to
6599@smallexample
6600  INTEGER :: status
6601  CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6602  IF (status /= 0) GOTO label
6603@end smallexample
6604
6605Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6606Programmers should consider the use of new stream IO feature in new code
6607for future portability. See also @ref{Fortran 2003 status}.
6608
6609@item @emph{Standard}:
6610GNU extension
6611
6612@item @emph{Class}:
6613Subroutine
6614
6615@item @emph{Syntax}:
6616@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6617
6618@item @emph{Arguments}:
6619@multitable @columnfractions .15 .70
6620@item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
6621@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6622@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6623Its value shall be either 0, 1 or 2.
6624@item @var{STATUS} @tab (Optional) shall be a scalar of type
6625@code{INTEGER(4)}.
6626@end multitable
6627
6628@item @emph{Example}:
6629@smallexample
6630PROGRAM test_fseek
6631  INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6632  INTEGER :: fd, offset, ierr
6633
6634  ierr   = 0
6635  offset = 5
6636  fd     = 10
6637
6638  OPEN(UNIT=fd, FILE="fseek.test")
6639  CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
6640  print *, FTELL(fd), ierr
6641
6642  CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
6643  print *, FTELL(fd), ierr
6644
6645  CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
6646  print *, FTELL(fd), ierr
6647
6648  CLOSE(UNIT=fd)
6649END PROGRAM
6650@end smallexample
6651
6652@item @emph{See also}:
6653@ref{FTELL}
6654@end table
6655
6656
6657
6658@node FSTAT
6659@section @code{FSTAT} --- Get file status
6660@fnindex FSTAT
6661@cindex file system, file status
6662
6663@table @asis
6664@item @emph{Description}:
6665@code{FSTAT} is identical to @ref{STAT}, except that information about an
6666already opened file is obtained.
6667
6668The elements in @code{VALUES} are the same as described by @ref{STAT}.
6669
6670This intrinsic is provided in both subroutine and function forms; however,
6671only one form can be used in any given program unit.
6672
6673@item @emph{Standard}:
6674GNU extension
6675
6676@item @emph{Class}:
6677Subroutine, function
6678
6679@item @emph{Syntax}:
6680@multitable @columnfractions .80
6681@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6682@item @code{STATUS = FSTAT(UNIT, VALUES)}
6683@end multitable
6684
6685@item @emph{Arguments}:
6686@multitable @columnfractions .15 .70
6687@item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
6688@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6689@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6690on success and a system specific error code otherwise.
6691@end multitable
6692
6693@item @emph{Example}:
6694See @ref{STAT} for an example.
6695
6696@item @emph{See also}:
6697To stat a link: @gol
6698@ref{LSTAT} @gol
6699To stat a file: @gol
6700@ref{STAT}
6701@end table
6702
6703
6704
6705@node FTELL
6706@section @code{FTELL} --- Current stream position
6707@fnindex FTELL
6708@cindex file operation, position
6709
6710@table @asis
6711@item @emph{Description}:
6712Retrieves the current position within an open file.
6713
6714This intrinsic is provided in both subroutine and function forms; however,
6715only one form can be used in any given program unit.
6716
6717@item @emph{Standard}:
6718GNU extension
6719
6720@item @emph{Class}:
6721Subroutine, function
6722
6723@item @emph{Syntax}:
6724@multitable @columnfractions .80
6725@item @code{CALL FTELL(UNIT, OFFSET)}
6726@item @code{OFFSET = FTELL(UNIT)}
6727@end multitable
6728
6729@item @emph{Arguments}:
6730@multitable @columnfractions .15 .70
6731@item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
6732@item @var{UNIT}    @tab Shall of type @code{INTEGER}.
6733@end multitable
6734
6735@item @emph{Return value}:
6736In either syntax, @var{OFFSET} is set to the current offset of unit
6737number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6738
6739@item @emph{Example}:
6740@smallexample
6741PROGRAM test_ftell
6742  INTEGER :: i
6743  OPEN(10, FILE="temp.dat")
6744  CALL ftell(10,i)
6745  WRITE(*,*) i
6746END PROGRAM
6747@end smallexample
6748
6749@item @emph{See also}:
6750@ref{FSEEK}
6751@end table
6752
6753
6754
6755@node GAMMA
6756@section @code{GAMMA} --- Gamma function
6757@fnindex GAMMA
6758@fnindex DGAMMA
6759@cindex Gamma function
6760@cindex Factorial function
6761
6762@table @asis
6763@item @emph{Description}:
6764@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6765integer values of @var{X} the Gamma function simplifies to the factorial
6766function @math{\Gamma(x)=(x-1)!}.
6767
6768@tex
6769$$
6770\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6771$$
6772@end tex
6773
6774@item @emph{Standard}:
6775Fortran 2008 and later
6776
6777@item @emph{Class}:
6778Elemental function
6779
6780@item @emph{Syntax}:
6781@code{X = GAMMA(X)}
6782
6783@item @emph{Arguments}:
6784@multitable @columnfractions .15 .70
6785@item @var{X} @tab Shall be of type @code{REAL} and neither zero
6786nor a negative integer.
6787@end multitable
6788
6789@item @emph{Return value}:
6790The return value is of type @code{REAL} of the same kind as @var{X}.
6791
6792@item @emph{Example}:
6793@smallexample
6794program test_gamma
6795  real :: x = 1.0
6796  x = gamma(x) ! returns 1.0
6797end program test_gamma
6798@end smallexample
6799
6800@item @emph{Specific names}:
6801@multitable @columnfractions .20 .23 .20 .33
6802@headitem Name             @tab Argument         @tab Return type       @tab Standard
6803@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU extension
6804@end multitable
6805
6806@item @emph{See also}:
6807Logarithm of the Gamma function: @gol
6808@ref{LOG_GAMMA}
6809@end table
6810
6811
6812
6813@node GERROR
6814@section @code{GERROR} --- Get last system error message
6815@fnindex GERROR
6816@cindex system, error handling
6817
6818@table @asis
6819@item @emph{Description}:
6820Returns the system error message corresponding to the last system error.
6821This resembles the functionality of @code{strerror(3)} in C.
6822
6823@item @emph{Standard}:
6824GNU extension
6825
6826@item @emph{Class}:
6827Subroutine
6828
6829@item @emph{Syntax}:
6830@code{CALL GERROR(RESULT)}
6831
6832@item @emph{Arguments}:
6833@multitable @columnfractions .15 .70
6834@item @var{RESULT}  @tab Shall be of type @code{CHARACTER} and of default kind.
6835@end multitable
6836
6837@item @emph{Example}:
6838@smallexample
6839PROGRAM test_gerror
6840  CHARACTER(len=100) :: msg
6841  CALL gerror(msg)
6842  WRITE(*,*) msg
6843END PROGRAM
6844@end smallexample
6845
6846@item @emph{See also}:
6847@ref{IERRNO}, @gol
6848@ref{PERROR}
6849@end table
6850
6851
6852
6853@node GETARG
6854@section @code{GETARG} --- Get command line arguments
6855@fnindex GETARG
6856@cindex command-line arguments
6857@cindex arguments, to program
6858
6859@table @asis
6860@item @emph{Description}:
6861Retrieve the @var{POS}-th argument that was passed on the
6862command line when the containing program was invoked.
6863
6864This intrinsic routine is provided for backwards compatibility with
6865GNU Fortran 77.  In new code, programmers should consider the use of
6866the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6867standard.
6868
6869@item @emph{Standard}:
6870GNU extension
6871
6872@item @emph{Class}:
6873Subroutine
6874
6875@item @emph{Syntax}:
6876@code{CALL GETARG(POS, VALUE)}
6877
6878@item @emph{Arguments}:
6879@multitable @columnfractions .15 .70
6880@item @var{POS}   @tab Shall be of type @code{INTEGER} and not wider than
6881the default integer kind; @math{@var{POS} \geq 0}
6882@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6883kind.
6884@end multitable
6885
6886@item @emph{Return value}:
6887After @code{GETARG} returns, the @var{VALUE} argument holds the
6888@var{POS}th command line argument. If @var{VALUE} cannot hold the
6889argument, it is truncated to fit the length of @var{VALUE}. If there are
6890less than @var{POS} arguments specified at the command line, @var{VALUE}
6891will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6892to the name of the program (on systems that support this feature).
6893
6894@item @emph{Example}:
6895@smallexample
6896PROGRAM test_getarg
6897  INTEGER :: i
6898  CHARACTER(len=32) :: arg
6899
6900  DO i = 1, iargc()
6901    CALL getarg(i, arg)
6902    WRITE (*,*) arg
6903  END DO
6904END PROGRAM
6905@end smallexample
6906
6907@item @emph{See also}:
6908GNU Fortran 77 compatibility function: @gol
6909@ref{IARGC} @gol
6910Fortran 2003 functions and subroutines: @gol
6911@ref{GET_COMMAND}, @gol
6912@ref{GET_COMMAND_ARGUMENT}, @gol
6913@ref{COMMAND_ARGUMENT_COUNT}
6914@end table
6915
6916
6917
6918@node GET_COMMAND
6919@section @code{GET_COMMAND} --- Get the entire command line
6920@fnindex GET_COMMAND
6921@cindex command-line arguments
6922@cindex arguments, to program
6923
6924@table @asis
6925@item @emph{Description}:
6926Retrieve the entire command line that was used to invoke the program.
6927
6928@item @emph{Standard}:
6929Fortran 2003 and later
6930
6931@item @emph{Class}:
6932Subroutine
6933
6934@item @emph{Syntax}:
6935@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6936
6937@item @emph{Arguments}:
6938@multitable @columnfractions .15 .70
6939@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6940of default kind.
6941@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6942default kind.
6943@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6944default kind.
6945@end multitable
6946
6947@item @emph{Return value}:
6948If @var{COMMAND} is present, stores the entire command line that was used
6949to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6950assigned the length of the command line. If @var{STATUS} is present, it
6951is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6952short to store the command line, or a positive value in case of an error.
6953
6954@item @emph{Example}:
6955@smallexample
6956PROGRAM test_get_command
6957  CHARACTER(len=255) :: cmd
6958  CALL get_command(cmd)
6959  WRITE (*,*) TRIM(cmd)
6960END PROGRAM
6961@end smallexample
6962
6963@item @emph{See also}:
6964@ref{GET_COMMAND_ARGUMENT}, @gol
6965@ref{COMMAND_ARGUMENT_COUNT}
6966@end table
6967
6968
6969
6970@node GET_COMMAND_ARGUMENT
6971@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6972@fnindex GET_COMMAND_ARGUMENT
6973@cindex command-line arguments
6974@cindex arguments, to program
6975
6976@table @asis
6977@item @emph{Description}:
6978Retrieve the @var{NUMBER}-th argument that was passed on the
6979command line when the containing program was invoked.
6980
6981@item @emph{Standard}:
6982Fortran 2003 and later
6983
6984@item @emph{Class}:
6985Subroutine
6986
6987@item @emph{Syntax}:
6988@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6989
6990@item @emph{Arguments}:
6991@multitable @columnfractions .15 .70
6992@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6993default kind, @math{@var{NUMBER} \geq 0}
6994@item @var{VALUE}  @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6995and of default kind.
6996@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6997and of default kind.
6998@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6999and of default kind.
7000@end multitable
7001
7002@item @emph{Return value}:
7003After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
7004@var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is
7005truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
7006arguments specified at the command line, @var{VALUE} will be filled with blanks.
7007If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
7008systems that support this feature). The @var{LENGTH} argument contains the
7009length of the @var{NUMBER}-th command line argument. If the argument retrieval
7010fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
7011command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
7012zero.
7013
7014@item @emph{Example}:
7015@smallexample
7016PROGRAM test_get_command_argument
7017  INTEGER :: i
7018  CHARACTER(len=32) :: arg
7019
7020  i = 0
7021  DO
7022    CALL get_command_argument(i, arg)
7023    IF (LEN_TRIM(arg) == 0) EXIT
7024
7025    WRITE (*,*) TRIM(arg)
7026    i = i+1
7027  END DO
7028END PROGRAM
7029@end smallexample
7030
7031@item @emph{See also}:
7032@ref{GET_COMMAND}, @gol
7033@ref{COMMAND_ARGUMENT_COUNT}
7034@end table
7035
7036
7037
7038@node GETCWD
7039@section @code{GETCWD} --- Get current working directory
7040@fnindex GETCWD
7041@cindex system, working directory
7042
7043@table @asis
7044@item @emph{Description}:
7045Get current working directory.
7046
7047This intrinsic is provided in both subroutine and function forms; however,
7048only one form can be used in any given program unit.
7049
7050@item @emph{Standard}:
7051GNU extension
7052
7053@item @emph{Class}:
7054Subroutine, function
7055
7056@item @emph{Syntax}:
7057@multitable @columnfractions .80
7058@item @code{CALL GETCWD(C [, STATUS])}
7059@item @code{STATUS = GETCWD(C)}
7060@end multitable
7061
7062@item @emph{Arguments}:
7063@multitable @columnfractions .15 .70
7064@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
7065@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
7066a system specific and nonzero error code otherwise.
7067@end multitable
7068
7069@item @emph{Example}:
7070@smallexample
7071PROGRAM test_getcwd
7072  CHARACTER(len=255) :: cwd
7073  CALL getcwd(cwd)
7074  WRITE(*,*) TRIM(cwd)
7075END PROGRAM
7076@end smallexample
7077
7078@item @emph{See also}:
7079@ref{CHDIR}
7080@end table
7081
7082
7083
7084@node GETENV
7085@section @code{GETENV} --- Get an environmental variable
7086@fnindex GETENV
7087@cindex environment variable
7088
7089@table @asis
7090@item @emph{Description}:
7091Get the @var{VALUE} of the environmental variable @var{NAME}.
7092
7093This intrinsic routine is provided for backwards compatibility with
7094GNU Fortran 77.  In new code, programmers should consider the use of
7095the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
70962003 standard.
7097
7098Note that @code{GETENV} need not be thread-safe. It is the
7099responsibility of the user to ensure that the environment is not being
7100updated concurrently with a call to the @code{GETENV} intrinsic.
7101
7102@item @emph{Standard}:
7103GNU extension
7104
7105@item @emph{Class}:
7106Subroutine
7107
7108@item @emph{Syntax}:
7109@code{CALL GETENV(NAME, VALUE)}
7110
7111@item @emph{Arguments}:
7112@multitable @columnfractions .15 .70
7113@item @var{NAME}  @tab Shall be of type @code{CHARACTER} and of default kind.
7114@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
7115@end multitable
7116
7117@item @emph{Return value}:
7118Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7119not large enough to hold the data, it is truncated. If @var{NAME}
7120is not set, @var{VALUE} will be filled with blanks.
7121
7122@item @emph{Example}:
7123@smallexample
7124PROGRAM test_getenv
7125  CHARACTER(len=255) :: homedir
7126  CALL getenv("HOME", homedir)
7127  WRITE (*,*) TRIM(homedir)
7128END PROGRAM
7129@end smallexample
7130
7131@item @emph{See also}:
7132@ref{GET_ENVIRONMENT_VARIABLE}
7133@end table
7134
7135
7136
7137@node GET_ENVIRONMENT_VARIABLE
7138@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
7139@fnindex GET_ENVIRONMENT_VARIABLE
7140@cindex environment variable
7141
7142@table @asis
7143@item @emph{Description}:
7144Get the @var{VALUE} of the environmental variable @var{NAME}.
7145
7146Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
7147is the responsibility of the user to ensure that the environment is
7148not being updated concurrently with a call to the
7149@code{GET_ENVIRONMENT_VARIABLE} intrinsic.
7150
7151@item @emph{Standard}:
7152Fortran 2003 and later
7153
7154@item @emph{Class}:
7155Subroutine
7156
7157@item @emph{Syntax}:
7158@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
7159
7160@item @emph{Arguments}:
7161@multitable @columnfractions .15 .70
7162@item @var{NAME}      @tab Shall be a scalar of type @code{CHARACTER}
7163and of default kind.
7164@item @var{VALUE}     @tab (Optional) Shall be a scalar of type @code{CHARACTER}
7165and of default kind.
7166@item @var{LENGTH}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
7167and of default kind.
7168@item @var{STATUS}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
7169and of default kind.
7170@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
7171and of default kind.
7172@end multitable
7173
7174@item @emph{Return value}:
7175Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7176not large enough to hold the data, it is truncated. If @var{NAME}
7177is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
7178contains the length needed for storing the environment variable @var{NAME}
7179or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
7180but too short for the environment variable; it is 1 if the environment
7181variable does not exist and 2 if the processor does not support environment
7182variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
7183present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
7184are significant; otherwise they are not part of the environment variable
7185name.
7186
7187@item @emph{Example}:
7188@smallexample
7189PROGRAM test_getenv
7190  CHARACTER(len=255) :: homedir
7191  CALL get_environment_variable("HOME", homedir)
7192  WRITE (*,*) TRIM(homedir)
7193END PROGRAM
7194@end smallexample
7195@end table
7196
7197
7198
7199@node GETGID
7200@section @code{GETGID} --- Group ID function
7201@fnindex GETGID
7202@cindex system, group ID
7203
7204@table @asis
7205@item @emph{Description}:
7206Returns the numerical group ID of the current process.
7207
7208@item @emph{Standard}:
7209GNU extension
7210
7211@item @emph{Class}:
7212Function
7213
7214@item @emph{Syntax}:
7215@code{RESULT = GETGID()}
7216
7217@item @emph{Return value}:
7218The return value of @code{GETGID} is an @code{INTEGER} of the default
7219kind.
7220
7221
7222@item @emph{Example}:
7223See @code{GETPID} for an example.
7224
7225@item @emph{See also}:
7226@ref{GETPID}, @gol
7227@ref{GETUID}
7228@end table
7229
7230
7231
7232@node GETLOG
7233@section @code{GETLOG} --- Get login name
7234@fnindex GETLOG
7235@cindex system, login name
7236@cindex login name
7237
7238@table @asis
7239@item @emph{Description}:
7240Gets the username under which the program is running.
7241
7242@item @emph{Standard}:
7243GNU extension
7244
7245@item @emph{Class}:
7246Subroutine
7247
7248@item @emph{Syntax}:
7249@code{CALL GETLOG(C)}
7250
7251@item @emph{Arguments}:
7252@multitable @columnfractions .15 .70
7253@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7254@end multitable
7255
7256@item @emph{Return value}:
7257Stores the current user name in @var{C}.  (On systems where POSIX
7258functions @code{geteuid} and @code{getpwuid} are not available, and
7259the @code{getlogin} function is not implemented either, this will
7260return a blank string.)
7261
7262@item @emph{Example}:
7263@smallexample
7264PROGRAM TEST_GETLOG
7265  CHARACTER(32) :: login
7266  CALL GETLOG(login)
7267  WRITE(*,*) login
7268END PROGRAM
7269@end smallexample
7270
7271@item @emph{See also}:
7272@ref{GETUID}
7273@end table
7274
7275
7276
7277@node GETPID
7278@section @code{GETPID} --- Process ID function
7279@fnindex GETPID
7280@cindex system, process ID
7281@cindex process ID
7282
7283@table @asis
7284@item @emph{Description}:
7285Returns the numerical process identifier of the current process.
7286
7287@item @emph{Standard}:
7288GNU extension
7289
7290@item @emph{Class}:
7291Function
7292
7293@item @emph{Syntax}:
7294@code{RESULT = GETPID()}
7295
7296@item @emph{Return value}:
7297The return value of @code{GETPID} is an @code{INTEGER} of the default
7298kind.
7299
7300
7301@item @emph{Example}:
7302@smallexample
7303program info
7304  print *, "The current process ID is ", getpid()
7305  print *, "Your numerical user ID is ", getuid()
7306  print *, "Your numerical group ID is ", getgid()
7307end program info
7308@end smallexample
7309
7310@item @emph{See also}:
7311@ref{GETGID}, @gol
7312@ref{GETUID}
7313@end table
7314
7315
7316
7317@node GETUID
7318@section @code{GETUID} --- User ID function
7319@fnindex GETUID
7320@cindex system, user ID
7321@cindex user id
7322
7323@table @asis
7324@item @emph{Description}:
7325Returns the numerical user ID of the current process.
7326
7327@item @emph{Standard}:
7328GNU extension
7329
7330@item @emph{Class}:
7331Function
7332
7333@item @emph{Syntax}:
7334@code{RESULT = GETUID()}
7335
7336@item @emph{Return value}:
7337The return value of @code{GETUID} is an @code{INTEGER} of the default
7338kind.
7339
7340
7341@item @emph{Example}:
7342See @code{GETPID} for an example.
7343
7344@item @emph{See also}:
7345@ref{GETPID}, @gol
7346@ref{GETLOG}
7347@end table
7348
7349
7350
7351@node GMTIME
7352@section @code{GMTIME} --- Convert time to GMT info
7353@fnindex GMTIME
7354@cindex time, conversion to GMT info
7355
7356@table @asis
7357@item @emph{Description}:
7358Given a system time value @var{TIME} (as provided by the @ref{TIME}
7359intrinsic), fills @var{VALUES} with values extracted from it appropriate
7360to the UTC time zone (Universal Coordinated Time, also known in some
7361countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7362
7363This intrinsic routine is provided for backwards compatibility with
7364GNU Fortran 77.  In new code, programmers should consider the use of
7365the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7366standard.
7367
7368@item @emph{Standard}:
7369GNU extension
7370
7371@item @emph{Class}:
7372Subroutine
7373
7374@item @emph{Syntax}:
7375@code{CALL GMTIME(TIME, VALUES)}
7376
7377@item @emph{Arguments}:
7378@multitable @columnfractions .15 .70
7379@item @var{TIME}   @tab An @code{INTEGER} scalar expression
7380corresponding to a system time, with @code{INTENT(IN)}.
7381@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7382with @code{INTENT(OUT)}.
7383@end multitable
7384
7385@item @emph{Return value}:
7386The elements of @var{VALUES} are assigned as follows:
7387@enumerate
7388@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7389seconds
7390@item Minutes after the hour, range 0--59
7391@item Hours past midnight, range 0--23
7392@item Day of month, range 1--31
7393@item Number of months since January, range 0--11
7394@item Years since 1900
7395@item Number of days since Sunday, range 0--6
7396@item Days since January 1, range 0--365
7397@item Daylight savings indicator: positive if daylight savings is in
7398effect, zero if not, and negative if the information is not available.
7399@end enumerate
7400
7401@item @emph{See also}:
7402@ref{DATE_AND_TIME}, @gol
7403@ref{CTIME}, @gol
7404@ref{LTIME}, @gol
7405@ref{TIME}, @gol
7406@ref{TIME8}
7407@end table
7408
7409
7410
7411@node HOSTNM
7412@section @code{HOSTNM} --- Get system host name
7413@fnindex HOSTNM
7414@cindex system, host name
7415
7416@table @asis
7417@item @emph{Description}:
7418Retrieves the host name of the system on which the program is running.
7419
7420This intrinsic is provided in both subroutine and function forms; however,
7421only one form can be used in any given program unit.
7422
7423@item @emph{Standard}:
7424GNU extension
7425
7426@item @emph{Class}:
7427Subroutine, function
7428
7429@item @emph{Syntax}:
7430@multitable @columnfractions .80
7431@item @code{CALL HOSTNM(C [, STATUS])}
7432@item @code{STATUS = HOSTNM(NAME)}
7433@end multitable
7434
7435@item @emph{Arguments}:
7436@multitable @columnfractions .15 .70
7437@item @var{C}    @tab Shall of type @code{CHARACTER} and of default kind.
7438@item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
7439Returns 0 on success, or a system specific error code otherwise.
7440@end multitable
7441
7442@item @emph{Return value}:
7443In either syntax, @var{NAME} is set to the current hostname if it can
7444be obtained, or to a blank string otherwise.
7445
7446@end table
7447
7448
7449
7450@node HUGE
7451@section @code{HUGE} --- Largest number of a kind
7452@fnindex HUGE
7453@cindex limits, largest number
7454@cindex model representation, largest number
7455
7456@table @asis
7457@item @emph{Description}:
7458@code{HUGE(X)} returns the largest number that is not an infinity in
7459the model of the type of @code{X}.
7460
7461@item @emph{Standard}:
7462Fortran 90 and later
7463
7464@item @emph{Class}:
7465Inquiry function
7466
7467@item @emph{Syntax}:
7468@code{RESULT = HUGE(X)}
7469
7470@item @emph{Arguments}:
7471@multitable @columnfractions .15 .70
7472@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7473@end multitable
7474
7475@item @emph{Return value}:
7476The return value is of the same type and kind as @var{X}
7477
7478@item @emph{Example}:
7479@smallexample
7480program test_huge_tiny
7481  print *, huge(0), huge(0.0), huge(0.0d0)
7482  print *, tiny(0.0), tiny(0.0d0)
7483end program test_huge_tiny
7484@end smallexample
7485@end table
7486
7487
7488
7489@node HYPOT
7490@section @code{HYPOT} --- Euclidean distance function
7491@fnindex HYPOT
7492@cindex Euclidean distance
7493
7494@table @asis
7495@item @emph{Description}:
7496@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7497@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7498
7499@item @emph{Standard}:
7500Fortran 2008 and later
7501
7502@item @emph{Class}:
7503Elemental function
7504
7505@item @emph{Syntax}:
7506@code{RESULT = HYPOT(X, Y)}
7507
7508@item @emph{Arguments}:
7509@multitable @columnfractions .15 .70
7510@item @var{X} @tab The type shall be @code{REAL}.
7511@item @var{Y} @tab The type and kind type parameter shall be the same as
7512@var{X}.
7513@end multitable
7514
7515@item @emph{Return value}:
7516The return value has the same type and kind type parameter as @var{X}.
7517
7518@item @emph{Example}:
7519@smallexample
7520program test_hypot
7521  real(4) :: x = 1.e0_4, y = 0.5e0_4
7522  x = hypot(x,y)
7523end program test_hypot
7524@end smallexample
7525@end table
7526
7527
7528
7529@node IACHAR
7530@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7531@fnindex IACHAR
7532@cindex @acronym{ASCII} collating sequence
7533@cindex collating sequence, @acronym{ASCII}
7534@cindex conversion, to integer
7535
7536@table @asis
7537@item @emph{Description}:
7538@code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7539in the first character position of @code{C}.
7540
7541@item @emph{Standard}:
7542Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7543
7544@item @emph{Class}:
7545Elemental function
7546
7547@item @emph{Syntax}:
7548@code{RESULT = IACHAR(C [, KIND])}
7549
7550@item @emph{Arguments}:
7551@multitable @columnfractions .15 .70
7552@item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7553@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7554expression indicating the kind parameter of the result.
7555@end multitable
7556
7557@item @emph{Return value}:
7558The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7559@var{KIND} is absent, the return value is of default integer kind.
7560
7561@item @emph{Example}:
7562@smallexample
7563program test_iachar
7564  integer i
7565  i = iachar(' ')
7566end program test_iachar
7567@end smallexample
7568
7569@item @emph{Note}:
7570See @ref{ICHAR} for a discussion of converting between numerical values
7571and formatted string representations.
7572
7573@item @emph{See also}:
7574@ref{ACHAR}, @gol
7575@ref{CHAR}, @gol
7576@ref{ICHAR}
7577@end table
7578
7579
7580
7581@node IALL
7582@section @code{IALL} --- Bitwise AND of array elements
7583@fnindex IALL
7584@cindex array, AND
7585@cindex bits, AND of array elements
7586
7587@table @asis
7588@item @emph{Description}:
7589Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7590if the corresponding element in @var{MASK} is @code{TRUE}.
7591
7592@item @emph{Standard}:
7593Fortran 2008 and later
7594
7595@item @emph{Class}:
7596Transformational function
7597
7598@item @emph{Syntax}:
7599@multitable @columnfractions .80
7600@item @code{RESULT = IALL(ARRAY[, MASK])}
7601@item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7602@end multitable
7603
7604@item @emph{Arguments}:
7605@multitable @columnfractions .15 .70
7606@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7607@item @var{DIM}   @tab (Optional) shall be a scalar of type
7608@code{INTEGER} with a value in the range from 1 to n, where n
7609equals the rank of @var{ARRAY}.
7610@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
7611and either be a scalar or an array of the same shape as @var{ARRAY}.
7612@end multitable
7613
7614@item @emph{Return value}:
7615The result is of the same type as @var{ARRAY}.
7616
7617If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7618@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7619the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7620dimension @var{DIM} dropped is returned.
7621
7622@item @emph{Example}:
7623@smallexample
7624PROGRAM test_iall
7625  INTEGER(1) :: a(2)
7626
7627  a(1) = b'00100100'
7628  a(2) = b'01101010'
7629
7630  ! prints 00100000
7631  PRINT '(b8.8)', IALL(a)
7632END PROGRAM
7633@end smallexample
7634
7635@item @emph{See also}:
7636@ref{IANY}, @gol
7637@ref{IPARITY}, @gol
7638@ref{IAND}
7639@end table
7640
7641
7642
7643@node IAND
7644@section @code{IAND} --- Bitwise logical and
7645@fnindex IAND
7646@fnindex BIAND
7647@fnindex IIAND
7648@fnindex JIAND
7649@fnindex KIAND
7650@cindex bitwise logical and
7651@cindex logical and, bitwise
7652
7653@table @asis
7654@item @emph{Description}:
7655Bitwise logical @code{AND}.
7656
7657@item @emph{Standard}:
7658Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
7659
7660@item @emph{Class}:
7661Elemental function
7662
7663@item @emph{Syntax}:
7664@code{RESULT = IAND(I, J)}
7665
7666@item @emph{Arguments}:
7667@multitable @columnfractions .15 .70
7668@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
7669@item @var{J} @tab The type shall be @code{INTEGER} with the same
7670kind type parameter as @var{I} or a boz-literal-constant.
7671@var{I} and @var{J} shall not both be boz-literal-constants.
7672@end multitable
7673
7674@item @emph{Return value}:
7675The return type is @code{INTEGER} with the kind type parameter of the
7676arguments.
7677A boz-literal-constant is converted to an @code{INTEGER} with the kind
7678type parameter of the other argument as-if a call to @ref{INT} occurred.
7679
7680@item @emph{Example}:
7681@smallexample
7682PROGRAM test_iand
7683  INTEGER :: a, b
7684  DATA a / Z'F' /, b / Z'3' /
7685  WRITE (*,*) IAND(a, b)
7686END PROGRAM
7687@end smallexample
7688
7689@item @emph{Specific names}:
7690@multitable @columnfractions .20 .23 .20 .33
7691@headitem Name            @tab Argument            @tab Return type       @tab Standard
7692@item @code{IAND(A)}   @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 90 and later
7693@item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7694@item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7695@item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7696@item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7697@end multitable
7698
7699@item @emph{See also}:
7700@ref{IOR}, @gol
7701@ref{IEOR}, @gol
7702@ref{IBITS}, @gol
7703@ref{IBSET}, @gol
7704@ref{IBCLR}, @gol
7705@ref{NOT}
7706@end table
7707
7708
7709
7710@node IANY
7711@section @code{IANY} --- Bitwise OR of array elements
7712@fnindex IANY
7713@cindex array, OR
7714@cindex bits, OR of array elements
7715
7716@table @asis
7717@item @emph{Description}:
7718Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7719dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7720
7721@item @emph{Standard}:
7722Fortran 2008 and later
7723
7724@item @emph{Class}:
7725Transformational function
7726
7727@item @emph{Syntax}:
7728@multitable @columnfractions .80
7729@item @code{RESULT = IANY(ARRAY[, MASK])}
7730@item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7731@end multitable
7732
7733@item @emph{Arguments}:
7734@multitable @columnfractions .15 .70
7735@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7736@item @var{DIM}   @tab (Optional) shall be a scalar of type
7737@code{INTEGER} with a value in the range from 1 to n, where n
7738equals the rank of @var{ARRAY}.
7739@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
7740and either be a scalar or an array of the same shape as @var{ARRAY}.
7741@end multitable
7742
7743@item @emph{Return value}:
7744The result is of the same type as @var{ARRAY}.
7745
7746If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7747@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7748the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7749dimension @var{DIM} dropped is returned.
7750
7751@item @emph{Example}:
7752@smallexample
7753PROGRAM test_iany
7754  INTEGER(1) :: a(2)
7755
7756  a(1) = b'00100100'
7757  a(2) = b'01101010'
7758
7759  ! prints 01101110
7760  PRINT '(b8.8)', IANY(a)
7761END PROGRAM
7762@end smallexample
7763
7764@item @emph{See also}:
7765@ref{IPARITY}, @gol
7766@ref{IALL}, @gol
7767@ref{IOR}
7768@end table
7769
7770
7771
7772@node IARGC
7773@section @code{IARGC} --- Get the number of command line arguments
7774@fnindex IARGC
7775@cindex command-line arguments
7776@cindex command-line arguments, number of
7777@cindex arguments, to program
7778
7779@table @asis
7780@item @emph{Description}:
7781@code{IARGC} returns the number of arguments passed on the
7782command line when the containing program was invoked.
7783
7784This intrinsic routine is provided for backwards compatibility with
7785GNU Fortran 77.  In new code, programmers should consider the use of
7786the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7787standard.
7788
7789@item @emph{Standard}:
7790GNU extension
7791
7792@item @emph{Class}:
7793Function
7794
7795@item @emph{Syntax}:
7796@code{RESULT = IARGC()}
7797
7798@item @emph{Arguments}:
7799None
7800
7801@item @emph{Return value}:
7802The number of command line arguments, type @code{INTEGER(4)}.
7803
7804@item @emph{Example}:
7805See @ref{GETARG}
7806
7807@item @emph{See also}:
7808GNU Fortran 77 compatibility subroutine: @gol
7809@ref{GETARG} @gol
7810Fortran 2003 functions and subroutines: @gol
7811@ref{GET_COMMAND}, @gol
7812@ref{GET_COMMAND_ARGUMENT}, @gol
7813@ref{COMMAND_ARGUMENT_COUNT}
7814@end table
7815
7816
7817
7818@node IBCLR
7819@section @code{IBCLR} --- Clear bit
7820@fnindex IBCLR
7821@fnindex BBCLR
7822@fnindex IIBCLR
7823@fnindex JIBCLR
7824@fnindex KIBCLR
7825@cindex bits, unset
7826@cindex bits, clear
7827
7828@table @asis
7829@item @emph{Description}:
7830@code{IBCLR} returns the value of @var{I} with the bit at position
7831@var{POS} set to zero.
7832
7833@item @emph{Standard}:
7834Fortran 90 and later, has overloads that are GNU extensions
7835
7836@item @emph{Class}:
7837Elemental function
7838
7839@item @emph{Syntax}:
7840@code{RESULT = IBCLR(I, POS)}
7841
7842@item @emph{Arguments}:
7843@multitable @columnfractions .15 .70
7844@item @var{I} @tab The type shall be @code{INTEGER}.
7845@item @var{POS} @tab The type shall be @code{INTEGER}.
7846@end multitable
7847
7848@item @emph{Return value}:
7849The return value is of type @code{INTEGER} and of the same kind as
7850@var{I}.
7851
7852@item @emph{Specific names}:
7853@multitable @columnfractions .20 .23 .20 .33
7854@headitem Name            @tab Argument            @tab Return type       @tab Standard
7855@item @code{IBCLR(A)}   @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 90 and later
7856@item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7857@item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7858@item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7859@item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7860@end multitable
7861
7862@item @emph{See also}:
7863@ref{IBITS}, @gol
7864@ref{IBSET}, @gol
7865@ref{IAND}, @gol
7866@ref{IOR}, @gol
7867@ref{IEOR}, @gol
7868@ref{MVBITS}
7869@end table
7870
7871
7872
7873@node IBITS
7874@section @code{IBITS} --- Bit extraction
7875@fnindex IBITS
7876@fnindex BBITS
7877@fnindex IIBITS
7878@fnindex JIBITS
7879@fnindex KIBITS
7880@cindex bits, get
7881@cindex bits, extract
7882
7883@table @asis
7884@item @emph{Description}:
7885@code{IBITS} extracts a field of length @var{LEN} from @var{I},
7886starting from bit position @var{POS} and extending left for @var{LEN}
7887bits.  The result is right-justified and the remaining bits are
7888zeroed.  The value of @code{POS+LEN} must be less than or equal to the
7889value @code{BIT_SIZE(I)}.
7890
7891@item @emph{Standard}:
7892Fortran 90 and later, has overloads that are GNU extensions
7893
7894@item @emph{Class}:
7895Elemental function
7896
7897@item @emph{Syntax}:
7898@code{RESULT = IBITS(I, POS, LEN)}
7899
7900@item @emph{Arguments}:
7901@multitable @columnfractions .15 .70
7902@item @var{I}   @tab The type shall be @code{INTEGER}.
7903@item @var{POS} @tab The type shall be @code{INTEGER}.
7904@item @var{LEN} @tab The type shall be @code{INTEGER}.
7905@end multitable
7906
7907@item @emph{Return value}:
7908The return value is of type @code{INTEGER} and of the same kind as
7909@var{I}.
7910
7911@item @emph{Specific names}:
7912@multitable @columnfractions .20 .23 .20 .33
7913@headitem Name            @tab Argument            @tab Return type       @tab Standard
7914@item @code{IBITS(A)}   @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 90 and later
7915@item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7916@item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7917@item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7918@item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7919@end multitable
7920
7921@item @emph{See also}:
7922@ref{BIT_SIZE}, @gol
7923@ref{IBCLR}, @gol
7924@ref{IBSET}, @gol
7925@ref{IAND}, @gol
7926@ref{IOR}, @gol
7927@ref{IEOR}
7928@end table
7929
7930
7931
7932@node IBSET
7933@section @code{IBSET} --- Set bit
7934@fnindex IBSET
7935@fnindex BBSET
7936@fnindex IIBSET
7937@fnindex JIBSET
7938@fnindex KIBSET
7939@cindex bits, set
7940
7941@table @asis
7942@item @emph{Description}:
7943@code{IBSET} returns the value of @var{I} with the bit at position
7944@var{POS} set to one.
7945
7946@item @emph{Standard}:
7947Fortran 90 and later, has overloads that are GNU extensions
7948
7949@item @emph{Class}:
7950Elemental function
7951
7952@item @emph{Syntax}:
7953@code{RESULT = IBSET(I, POS)}
7954
7955@item @emph{Arguments}:
7956@multitable @columnfractions .15 .70
7957@item @var{I} @tab The type shall be @code{INTEGER}.
7958@item @var{POS} @tab The type shall be @code{INTEGER}.
7959@end multitable
7960
7961@item @emph{Return value}:
7962The return value is of type @code{INTEGER} and of the same kind as
7963@var{I}.
7964
7965@item @emph{Specific names}:
7966@multitable @columnfractions .20 .23 .20 .33
7967@headitem Name            @tab Argument            @tab Return type       @tab Standard
7968@item @code{IBSET(A)}   @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 90 and later
7969@item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7970@item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7971@item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7972@item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7973@end multitable
7974
7975@item @emph{See also}:
7976@ref{IBCLR}, @gol
7977@ref{IBITS}, @gol
7978@ref{IAND}, @gol
7979@ref{IOR}, @gol
7980@ref{IEOR}, @gol
7981@ref{MVBITS}
7982@end table
7983
7984
7985
7986@node ICHAR
7987@section @code{ICHAR} --- Character-to-integer conversion function
7988@fnindex ICHAR
7989@cindex conversion, to integer
7990
7991@table @asis
7992@item @emph{Description}:
7993@code{ICHAR(C)} returns the code for the character in the first character
7994position of @code{C} in the system's native character set.
7995The correspondence between characters and their codes is not necessarily
7996the same across different GNU Fortran implementations.
7997
7998@item @emph{Standard}:
7999Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8000
8001@item @emph{Class}:
8002Elemental function
8003
8004@item @emph{Syntax}:
8005@code{RESULT = ICHAR(C [, KIND])}
8006
8007@item @emph{Arguments}:
8008@multitable @columnfractions .15 .70
8009@item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
8010@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8011expression indicating the kind parameter of the result.
8012@end multitable
8013
8014@item @emph{Return value}:
8015The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8016@var{KIND} is absent, the return value is of default integer kind.
8017
8018@item @emph{Example}:
8019@smallexample
8020program test_ichar
8021  integer i
8022  i = ichar(' ')
8023end program test_ichar
8024@end smallexample
8025
8026@item @emph{Specific names}:
8027@multitable @columnfractions .20 .23 .20 .33
8028@headitem Name             @tab Argument             @tab Return type       @tab Standard
8029@item @code{ICHAR(C)}  @tab @code{CHARACTER C}   @tab @code{INTEGER(4)}    @tab Fortran 77 and later
8030@end multitable
8031
8032@item @emph{Note}:
8033No intrinsic exists to convert between a numeric value and a formatted
8034character string representation -- for instance, given the
8035@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
8036@code{REAL} value with the value 154, or vice versa. Instead, this
8037functionality is provided by internal-file I/O, as in the following
8038example:
8039@smallexample
8040program read_val
8041  integer value
8042  character(len=10) string, string2
8043  string = '154'
8044
8045  ! Convert a string to a numeric value
8046  read (string,'(I10)') value
8047  print *, value
8048
8049  ! Convert a value to a formatted string
8050  write (string2,'(I10)') value
8051  print *, string2
8052end program read_val
8053@end smallexample
8054
8055@item @emph{See also}:
8056@ref{ACHAR}, @gol
8057@ref{CHAR}, @gol
8058@ref{IACHAR}
8059@end table
8060
8061
8062
8063@node IDATE
8064@section @code{IDATE} --- Get current local time subroutine (day/month/year)
8065@fnindex IDATE
8066@cindex date, current
8067@cindex current date
8068
8069@table @asis
8070@item @emph{Description}:
8071@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8072current local time. The day (in the range 1-31), month (in the range 1-12),
8073and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
8074The year has four significant digits.
8075
8076This intrinsic routine is provided for backwards compatibility with
8077GNU Fortran 77.  In new code, programmers should consider the use of
8078the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8079standard.
8080
8081@item @emph{Standard}:
8082GNU extension
8083
8084@item @emph{Class}:
8085Subroutine
8086
8087@item @emph{Syntax}:
8088@code{CALL IDATE(VALUES)}
8089
8090@item @emph{Arguments}:
8091@multitable @columnfractions .15 .70
8092@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
8093the kind shall be the default integer kind.
8094@end multitable
8095
8096@item @emph{Return value}:
8097Does not return anything.
8098
8099@item @emph{Example}:
8100@smallexample
8101program test_idate
8102  integer, dimension(3) :: tarray
8103  call idate(tarray)
8104  print *, tarray(1)
8105  print *, tarray(2)
8106  print *, tarray(3)
8107end program test_idate
8108@end smallexample
8109
8110@item @emph{See also}:
8111@ref{DATE_AND_TIME}
8112@end table
8113
8114
8115@node IEOR
8116@section @code{IEOR} --- Bitwise logical exclusive or
8117@fnindex IEOR
8118@fnindex BIEOR
8119@fnindex IIEOR
8120@fnindex JIEOR
8121@fnindex KIEOR
8122@cindex bitwise logical exclusive or
8123@cindex logical exclusive or, bitwise
8124
8125@table @asis
8126@item @emph{Description}:
8127@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
8128@var{J}.
8129
8130@item @emph{Standard}:
8131Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8132
8133@item @emph{Class}:
8134Elemental function
8135
8136@item @emph{Syntax}:
8137@code{RESULT = IEOR(I, J)}
8138
8139@item @emph{Arguments}:
8140@multitable @columnfractions .15 .70
8141@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8142@item @var{J} @tab The type shall be @code{INTEGER} with the same
8143kind type parameter as @var{I} or a boz-literal-constant.
8144@var{I} and @var{J} shall not both be boz-literal-constants.
8145@end multitable
8146
8147@item @emph{Return value}:
8148The return type is @code{INTEGER} with the kind type parameter of the
8149arguments.
8150A boz-literal-constant is converted to an @code{INTEGER} with the kind
8151type parameter of the other argument as-if a call to @ref{INT} occurred.
8152
8153@item @emph{Specific names}:
8154@multitable @columnfractions .20 .23 .20 .33
8155@headitem Name            @tab Argument            @tab Return type       @tab Standard
8156@item @code{IEOR(A)}  @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 90 and later
8157@item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8158@item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8159@item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8160@item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8161@end multitable
8162
8163@item @emph{See also}:
8164@ref{IOR}, @gol
8165@ref{IAND}, @gol
8166@ref{IBITS}, @gol
8167@ref{IBSET}, @gol
8168@ref{IBCLR}, @gol
8169@ref{NOT}
8170@end table
8171
8172
8173
8174@node IERRNO
8175@section @code{IERRNO} --- Get the last system error number
8176@fnindex IERRNO
8177@cindex system, error handling
8178
8179@table @asis
8180@item @emph{Description}:
8181Returns the last system error number, as given by the C @code{errno}
8182variable.
8183
8184@item @emph{Standard}:
8185GNU extension
8186
8187@item @emph{Class}:
8188Function
8189
8190@item @emph{Syntax}:
8191@code{RESULT = IERRNO()}
8192
8193@item @emph{Arguments}:
8194None
8195
8196@item @emph{Return value}:
8197The return value is of type @code{INTEGER} and of the default integer
8198kind.
8199
8200@item @emph{See also}:
8201@ref{PERROR}
8202@end table
8203
8204
8205
8206@node IMAGE_INDEX
8207@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
8208@fnindex IMAGE_INDEX
8209@cindex coarray, @code{IMAGE_INDEX}
8210@cindex images, cosubscript to image index conversion
8211
8212@table @asis
8213@item @emph{Description}:
8214Returns the image index belonging to a cosubscript.
8215
8216@item @emph{Standard}:
8217Fortran 2008 and later
8218
8219@item @emph{Class}:
8220Inquiry function.
8221
8222@item @emph{Syntax}:
8223@code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
8224
8225@item @emph{Arguments}:
8226@multitable @columnfractions .15 .70
8227@item @var{COARRAY} @tab Coarray of any type.
8228@item @var{SUB}     @tab default integer rank-1 array of a size equal to
8229the corank of @var{COARRAY}.
8230@end multitable
8231
8232
8233@item @emph{Return value}:
8234Scalar default integer with the value of the image index which corresponds
8235to the cosubscripts. For invalid cosubscripts the result is zero.
8236
8237@item @emph{Example}:
8238@smallexample
8239INTEGER :: array[2,-1:4,8,*]
8240! Writes  28 (or 0 if there are fewer than 28 images)
8241WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
8242@end smallexample
8243
8244@item @emph{See also}:
8245@ref{THIS_IMAGE}, @gol
8246@ref{NUM_IMAGES}
8247@end table
8248
8249
8250
8251@node INDEX intrinsic
8252@section @code{INDEX} --- Position of a substring within a string
8253@fnindex INDEX
8254@cindex substring position
8255@cindex string, find substring
8256
8257@table @asis
8258@item @emph{Description}:
8259Returns the position of the start of the first occurrence of string
8260@var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
8261@var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If
8262the @var{BACK} argument is present and true, the return value is the
8263start of the last occurrence rather than the first.
8264
8265@item @emph{Standard}:
8266Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8267
8268@item @emph{Class}:
8269Elemental function
8270
8271@item @emph{Syntax}:
8272@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8273
8274@item @emph{Arguments}:
8275@multitable @columnfractions .15 .70
8276@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8277@code{INTENT(IN)}
8278@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8279@code{INTENT(IN)}
8280@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8281@code{INTENT(IN)}
8282@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8283expression indicating the kind parameter of the result.
8284@end multitable
8285
8286@item @emph{Return value}:
8287The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8288@var{KIND} is absent, the return value is of default integer kind.
8289
8290@item @emph{Specific names}:
8291@multitable @columnfractions .35 .15 .17 .30
8292@headitem Name                            @tab Argument           @tab Return type       @tab Standard
8293@item @code{INDEX(STRING,SUBSTRING)} @tab @code{CHARACTER}   @tab @code{INTEGER(4)} @tab Fortran 77 and later
8294@end multitable
8295
8296@item @emph{See also}:
8297@ref{SCAN}, @gol
8298@ref{VERIFY}
8299@end table
8300
8301
8302
8303@node INT
8304@section @code{INT} --- Convert to integer type
8305@fnindex INT
8306@fnindex IFIX
8307@fnindex IDINT
8308@cindex conversion, to integer
8309
8310@table @asis
8311@item @emph{Description}:
8312Convert to integer type
8313
8314@item @emph{Standard}:
8315Fortran 77 and later, with boz-literal-constant Fortran 2008 and later.
8316
8317@item @emph{Class}:
8318Elemental function
8319
8320@item @emph{Syntax}:
8321@code{RESULT = INT(A [, KIND))}
8322
8323@item @emph{Arguments}:
8324@multitable @columnfractions .15 .70
8325@item @var{A}    @tab Shall be of type @code{INTEGER},
8326@code{REAL}, or @code{COMPLEX} or a boz-literal-constant.
8327@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8328expression indicating the kind parameter of the result.
8329@end multitable
8330
8331@item @emph{Return value}:
8332These functions return a @code{INTEGER} variable or array under
8333the following rules:
8334
8335@table @asis
8336@item (A)
8337If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8338@item (B)
8339If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8340equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8341whose magnitude is the largest integer that does not exceed the magnitude
8342of @var{A} and whose sign is the same as the sign of @var{A}.
8343@item (C)
8344If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8345@end table
8346
8347@item @emph{Example}:
8348@smallexample
8349program test_int
8350  integer :: i = 42
8351  complex :: z = (-3.7, 1.0)
8352  print *, int(i)
8353  print *, int(z), int(z,8)
8354end program
8355@end smallexample
8356
8357@item @emph{Specific names}:
8358@multitable @columnfractions .20 .23 .20 .33
8359@headitem Name            @tab Argument          @tab Return type       @tab Standard
8360@item @code{INT(A)}   @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
8361@item @code{IFIX(A)}  @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
8362@item @code{IDINT(A)} @tab @code{REAL(8) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
8363@end multitable
8364
8365@end table
8366
8367
8368@node INT2
8369@section @code{INT2} --- Convert to 16-bit integer type
8370@fnindex INT2
8371@cindex conversion, to integer
8372
8373@table @asis
8374@item @emph{Description}:
8375Convert to a @code{KIND=2} integer type. This is equivalent to the
8376standard @code{INT} intrinsic with an optional argument of
8377@code{KIND=2}, and is only included for backwards compatibility.
8378
8379@item @emph{Standard}:
8380GNU extension
8381
8382@item @emph{Class}:
8383Elemental function
8384
8385@item @emph{Syntax}:
8386@code{RESULT = INT2(A)}
8387
8388@item @emph{Arguments}:
8389@multitable @columnfractions .15 .70
8390@item @var{A}    @tab Shall be of type @code{INTEGER},
8391@code{REAL}, or @code{COMPLEX}.
8392@end multitable
8393
8394@item @emph{Return value}:
8395The return value is a @code{INTEGER(2)} variable.
8396
8397@item @emph{See also}:
8398@ref{INT}, @gol
8399@ref{INT8}
8400@end table
8401
8402
8403
8404@node INT8
8405@section @code{INT8} --- Convert to 64-bit integer type
8406@fnindex INT8
8407@cindex conversion, to integer
8408
8409@table @asis
8410@item @emph{Description}:
8411Convert to a @code{KIND=8} integer type. This is equivalent to the
8412standard @code{INT} intrinsic with an optional argument of
8413@code{KIND=8}, and is only included for backwards compatibility.
8414
8415@item @emph{Standard}:
8416GNU extension
8417
8418@item @emph{Class}:
8419Elemental function
8420
8421@item @emph{Syntax}:
8422@code{RESULT = INT8(A)}
8423
8424@item @emph{Arguments}:
8425@multitable @columnfractions .15 .70
8426@item @var{A}    @tab Shall be of type @code{INTEGER},
8427@code{REAL}, or @code{COMPLEX}.
8428@end multitable
8429
8430@item @emph{Return value}:
8431The return value is a @code{INTEGER(8)} variable.
8432
8433@item @emph{See also}:
8434@ref{INT}, @gol
8435@ref{INT2}
8436@end table
8437
8438
8439
8440@node IOR
8441@section @code{IOR} --- Bitwise logical or
8442@fnindex IOR
8443@fnindex BIOR
8444@fnindex IIOR
8445@fnindex JIOR
8446@fnindex KIOR
8447@cindex bitwise logical or
8448@cindex logical or, bitwise
8449
8450@table @asis
8451@item @emph{Description}:
8452@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8453@var{J}.
8454
8455@item @emph{Standard}:
8456Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8457
8458@item @emph{Class}:
8459Elemental function
8460
8461@item @emph{Syntax}:
8462@code{RESULT = IOR(I, J)}
8463
8464@item @emph{Arguments}:
8465@multitable @columnfractions .15 .70
8466@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8467@item @var{J} @tab The type shall be @code{INTEGER} with the same
8468kind type parameter as @var{I} or a boz-literal-constant.
8469@var{I} and @var{J} shall not both be boz-literal-constants.
8470@end multitable
8471
8472@item @emph{Return value}:
8473The return type is @code{INTEGER} with the kind type parameter of the
8474arguments.
8475A boz-literal-constant is converted to an @code{INTEGER} with the kind
8476type parameter of the other argument as-if a call to @ref{INT} occurred.
8477
8478@item @emph{Specific names}:
8479@multitable @columnfractions .20 .23 .20 .33
8480@headitem Name            @tab Argument            @tab Return type       @tab Standard
8481@item @code{IOR(A)}   @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 90 and later
8482@item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8483@item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8484@item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8485@item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8486@end multitable
8487
8488@item @emph{See also}:
8489@ref{IEOR}, @gol
8490@ref{IAND}, @gol
8491@ref{IBITS}, @gol
8492@ref{IBSET}, @gol
8493@ref{IBCLR}, @gol
8494@ref{NOT}
8495@end table
8496
8497
8498
8499@node IPARITY
8500@section @code{IPARITY} --- Bitwise XOR of array elements
8501@fnindex IPARITY
8502@cindex array, parity
8503@cindex array, XOR
8504@cindex bits, XOR of array elements
8505
8506@table @asis
8507@item @emph{Description}:
8508Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8509dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8510
8511@item @emph{Standard}:
8512Fortran 2008 and later
8513
8514@item @emph{Class}:
8515Transformational function
8516
8517@item @emph{Syntax}:
8518@multitable @columnfractions .80
8519@item @code{RESULT = IPARITY(ARRAY[, MASK])}
8520@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8521@end multitable
8522
8523@item @emph{Arguments}:
8524@multitable @columnfractions .15 .70
8525@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8526@item @var{DIM}   @tab (Optional) shall be a scalar of type
8527@code{INTEGER} with a value in the range from 1 to n, where n
8528equals the rank of @var{ARRAY}.
8529@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
8530and either be a scalar or an array of the same shape as @var{ARRAY}.
8531@end multitable
8532
8533@item @emph{Return value}:
8534The result is of the same type as @var{ARRAY}.
8535
8536If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8537@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8538the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8539dimension @var{DIM} dropped is returned.
8540
8541@item @emph{Example}:
8542@smallexample
8543PROGRAM test_iparity
8544  INTEGER(1) :: a(2)
8545
8546  a(1) = int(b'00100100', 1)
8547  a(2) = int(b'01101010', 1)
8548
8549  ! prints 01001110
8550  PRINT '(b8.8)', IPARITY(a)
8551END PROGRAM
8552@end smallexample
8553
8554@item @emph{See also}:
8555@ref{IANY}, @gol
8556@ref{IALL}, @gol
8557@ref{IEOR}, @gol
8558@ref{PARITY}
8559@end table
8560
8561
8562
8563@node IRAND
8564@section @code{IRAND} --- Integer pseudo-random number
8565@fnindex IRAND
8566@cindex random number generation
8567
8568@table @asis
8569@item @emph{Description}:
8570@code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8571distribution between 0 and a system-dependent limit (which is in most
8572cases 2147483647). If @var{FLAG} is 0, the next number
8573in the current sequence is returned; if @var{FLAG} is 1, the generator
8574is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8575it is used as a new seed with @code{SRAND}.
8576
8577This intrinsic routine is provided for backwards compatibility with
8578GNU Fortran 77. It implements a simple modulo generator as provided
8579by @command{g77}. For new code, one should consider the use of
8580@ref{RANDOM_NUMBER} as it implements a superior algorithm.
8581
8582@item @emph{Standard}:
8583GNU extension
8584
8585@item @emph{Class}:
8586Function
8587
8588@item @emph{Syntax}:
8589@code{RESULT = IRAND(I)}
8590
8591@item @emph{Arguments}:
8592@multitable @columnfractions .15 .70
8593@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8594@end multitable
8595
8596@item @emph{Return value}:
8597The return value is of @code{INTEGER(kind=4)} type.
8598
8599@item @emph{Example}:
8600@smallexample
8601program test_irand
8602  integer,parameter :: seed = 86456
8603
8604  call srand(seed)
8605  print *, irand(), irand(), irand(), irand()
8606  print *, irand(seed), irand(), irand(), irand()
8607end program test_irand
8608@end smallexample
8609
8610@end table
8611
8612
8613
8614@node IS_CONTIGUOUS
8615@section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous
8616@fnindex IS_IOSTAT_EOR
8617@cindex array, contiguity
8618
8619@table @asis
8620@item @emph{Description}:
8621@code{IS_CONTIGUOUS} tests whether an array is contiguous.
8622
8623@item @emph{Standard}:
8624Fortran 2008 and later
8625
8626@item @emph{Class}:
8627Inquiry function
8628
8629@item @emph{Syntax}:
8630@code{RESULT = IS_CONTIGUOUS(ARRAY)}
8631
8632@item @emph{Arguments}:
8633@multitable @columnfractions .15 .70
8634@item @var{ARRAY} @tab Shall be an array of any type.
8635@end multitable
8636
8637@item @emph{Return value}:
8638Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8639@var{ARRAY} is contiguous and false otherwise.
8640
8641@item @emph{Example}:
8642@smallexample
8643program test
8644  integer :: a(10)
8645  a = [1,2,3,4,5,6,7,8,9,10]
8646  call sub (a)      ! every element, is contiguous
8647  call sub (a(::2)) ! every other element, is noncontiguous
8648contains
8649  subroutine sub (x)
8650    integer :: x(:)
8651    if (is_contiguous (x)) then
8652      write (*,*) 'X is contiguous'
8653    else
8654      write (*,*) 'X is not contiguous'
8655    end if
8656  end subroutine sub
8657end program test
8658@end smallexample
8659@end table
8660
8661
8662
8663@node IS_IOSTAT_END
8664@section @code{IS_IOSTAT_END} --- Test for end-of-file value
8665@fnindex IS_IOSTAT_END
8666@cindex @code{IOSTAT}, end of file
8667
8668@table @asis
8669@item @emph{Description}:
8670@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8671status ``end of file''. The function is equivalent to comparing the variable
8672with the @code{IOSTAT_END} parameter of the intrinsic module
8673@code{ISO_FORTRAN_ENV}.
8674
8675@item @emph{Standard}:
8676Fortran 2003 and later
8677
8678@item @emph{Class}:
8679Elemental function
8680
8681@item @emph{Syntax}:
8682@code{RESULT = IS_IOSTAT_END(I)}
8683
8684@item @emph{Arguments}:
8685@multitable @columnfractions .15 .70
8686@item @var{I} @tab Shall be of the type @code{INTEGER}.
8687@end multitable
8688
8689@item @emph{Return value}:
8690Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8691@var{I} has the value which indicates an end of file condition for
8692@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8693
8694@item @emph{Example}:
8695@smallexample
8696PROGRAM iostat
8697  IMPLICIT NONE
8698  INTEGER :: stat, i
8699  OPEN(88, FILE='test.dat')
8700  READ(88, *, IOSTAT=stat) i
8701  IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8702END PROGRAM
8703@end smallexample
8704@end table
8705
8706
8707
8708@node IS_IOSTAT_EOR
8709@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8710@fnindex IS_IOSTAT_EOR
8711@cindex @code{IOSTAT}, end of record
8712
8713@table @asis
8714@item @emph{Description}:
8715@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8716status ``end of record''. The function is equivalent to comparing the
8717variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8718@code{ISO_FORTRAN_ENV}.
8719
8720@item @emph{Standard}:
8721Fortran 2003 and later
8722
8723@item @emph{Class}:
8724Elemental function
8725
8726@item @emph{Syntax}:
8727@code{RESULT = IS_IOSTAT_EOR(I)}
8728
8729@item @emph{Arguments}:
8730@multitable @columnfractions .15 .70
8731@item @var{I} @tab Shall be of the type @code{INTEGER}.
8732@end multitable
8733
8734@item @emph{Return value}:
8735Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8736@var{I} has the value which indicates an end of file condition for
8737@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8738
8739@item @emph{Example}:
8740@smallexample
8741PROGRAM iostat
8742  IMPLICIT NONE
8743  INTEGER :: stat, i(50)
8744  OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8745  READ(88, IOSTAT=stat) i
8746  IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8747END PROGRAM
8748@end smallexample
8749@end table
8750
8751
8752@node ISATTY
8753@section @code{ISATTY} --- Whether a unit is a terminal device.
8754@fnindex ISATTY
8755@cindex system, terminal
8756
8757@table @asis
8758@item @emph{Description}:
8759Determine whether a unit is connected to a terminal device.
8760
8761@item @emph{Standard}:
8762GNU extension
8763
8764@item @emph{Class}:
8765Function
8766
8767@item @emph{Syntax}:
8768@code{RESULT = ISATTY(UNIT)}
8769
8770@item @emph{Arguments}:
8771@multitable @columnfractions .15 .70
8772@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8773@end multitable
8774
8775@item @emph{Return value}:
8776Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8777device, @code{.FALSE.} otherwise.
8778
8779@item @emph{Example}:
8780@smallexample
8781PROGRAM test_isatty
8782  INTEGER(kind=1) :: unit
8783  DO unit = 1, 10
8784    write(*,*) isatty(unit=unit)
8785  END DO
8786END PROGRAM
8787@end smallexample
8788@item @emph{See also}:
8789@ref{TTYNAM}
8790@end table
8791
8792
8793
8794@node ISHFT
8795@section @code{ISHFT} --- Shift bits
8796@fnindex ISHFT
8797@fnindex BSHFT
8798@fnindex IISHFT
8799@fnindex JISHFT
8800@fnindex KISHFT
8801@cindex bits, shift
8802
8803@table @asis
8804@item @emph{Description}:
8805@code{ISHFT} returns a value corresponding to @var{I} with all of the
8806bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
8807zero corresponds to a left shift, a value of zero corresponds to no
8808shift, and a value less than zero corresponds to a right shift.  If the
8809absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8810value is undefined.  Bits shifted out from the left end or right end are
8811lost; zeros are shifted in from the opposite end.
8812
8813@item @emph{Standard}:
8814Fortran 90 and later, has overloads that are GNU extensions
8815
8816@item @emph{Class}:
8817Elemental function
8818
8819@item @emph{Syntax}:
8820@code{RESULT = ISHFT(I, SHIFT)}
8821
8822@item @emph{Arguments}:
8823@multitable @columnfractions .15 .70
8824@item @var{I} @tab The type shall be @code{INTEGER}.
8825@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8826@end multitable
8827
8828@item @emph{Return value}:
8829The return value is of type @code{INTEGER} and of the same kind as
8830@var{I}.
8831
8832@item @emph{Specific names}:
8833@multitable @columnfractions .20 .23 .20 .33
8834@headitem Name            @tab Argument            @tab Return type       @tab Standard
8835@item @code{ISHFT(A)}   @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 90 and later
8836@item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8837@item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8838@item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8839@item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8840@end multitable
8841
8842@item @emph{See also}:
8843@ref{ISHFTC}
8844@end table
8845
8846
8847
8848@node ISHFTC
8849@section @code{ISHFTC} --- Shift bits circularly
8850@fnindex ISHFTC
8851@fnindex BSHFTC
8852@fnindex IISHFTC
8853@fnindex JISHFTC
8854@fnindex KISHFTC
8855@cindex bits, shift circular
8856
8857@table @asis
8858@item @emph{Description}:
8859@code{ISHFTC} returns a value corresponding to @var{I} with the
8860rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8861is, bits shifted out one end are shifted into the opposite end.  A value
8862of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8863zero corresponds to no shift, and a value less than zero corresponds to
8864a right shift.  The absolute value of @var{SHIFT} must be less than
8865@var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
8866equivalent to @code{BIT_SIZE(I)}.
8867
8868@item @emph{Standard}:
8869Fortran 90 and later, has overloads that are GNU extensions
8870
8871@item @emph{Class}:
8872Elemental function
8873
8874@item @emph{Syntax}:
8875@code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8876
8877@item @emph{Arguments}:
8878@multitable @columnfractions .15 .70
8879@item @var{I} @tab The type shall be @code{INTEGER}.
8880@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8881@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8882the value must be greater than zero and less than or equal to
8883@code{BIT_SIZE(I)}.
8884@end multitable
8885
8886@item @emph{Return value}:
8887The return value is of type @code{INTEGER} and of the same kind as
8888@var{I}.
8889
8890@item @emph{Specific names}:
8891@multitable @columnfractions .20 .23 .20 .33
8892@headitem Name            @tab Argument            @tab Return type       @tab Standard
8893@item @code{ISHFTC(A)}   @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 90 and later
8894@item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8895@item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8896@item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8897@item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8898@end multitable
8899
8900@item @emph{See also}:
8901@ref{ISHFT}
8902@end table
8903
8904
8905
8906@node ISNAN
8907@section @code{ISNAN} --- Test for a NaN
8908@fnindex ISNAN
8909@cindex IEEE, ISNAN
8910
8911@table @asis
8912@item @emph{Description}:
8913@code{ISNAN} tests whether a floating-point value is an IEEE
8914Not-a-Number (NaN).
8915@item @emph{Standard}:
8916GNU extension
8917
8918@item @emph{Class}:
8919Elemental function
8920
8921@item @emph{Syntax}:
8922@code{ISNAN(X)}
8923
8924@item @emph{Arguments}:
8925@multitable @columnfractions .15 .70
8926@item @var{X} @tab Variable of the type @code{REAL}.
8927
8928@end multitable
8929
8930@item @emph{Return value}:
8931Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8932if @var{X} is a NaN and @code{FALSE} otherwise.
8933
8934@item @emph{Example}:
8935@smallexample
8936program test_nan
8937  implicit none
8938  real :: x
8939  x = -1.0
8940  x = sqrt(x)
8941  if (isnan(x)) stop '"x" is a NaN'
8942end program test_nan
8943@end smallexample
8944@end table
8945
8946
8947
8948@node ITIME
8949@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8950@fnindex ITIME
8951@cindex time, current
8952@cindex current time
8953
8954@table @asis
8955@item @emph{Description}:
8956@code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
8957current local time. The hour (in the range 1-24), minute (in the range 1-60),
8958and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8959respectively.
8960
8961This intrinsic routine is provided for backwards compatibility with
8962GNU Fortran 77.  In new code, programmers should consider the use of
8963the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8964standard.
8965
8966@item @emph{Standard}:
8967GNU extension
8968
8969@item @emph{Class}:
8970Subroutine
8971
8972@item @emph{Syntax}:
8973@code{CALL ITIME(VALUES)}
8974
8975@item @emph{Arguments}:
8976@multitable @columnfractions .15 .70
8977@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8978and the kind shall be the default integer kind.
8979@end multitable
8980
8981@item @emph{Return value}:
8982Does not return anything.
8983
8984
8985@item @emph{Example}:
8986@smallexample
8987program test_itime
8988  integer, dimension(3) :: tarray
8989  call itime(tarray)
8990  print *, tarray(1)
8991  print *, tarray(2)
8992  print *, tarray(3)
8993end program test_itime
8994@end smallexample
8995
8996@item @emph{See also}:
8997@ref{DATE_AND_TIME}
8998@end table
8999
9000
9001
9002@node KILL
9003@section @code{KILL} --- Send a signal to a process
9004@fnindex KILL
9005
9006@table @asis
9007@item @emph{Description}:
9008Sends the signal specified by @var{SIG} to the process @var{PID}.
9009See @code{kill(2)}.
9010
9011This intrinsic is provided in both subroutine and function forms;
9012however, only one form can be used in any given program unit.
9013@item @emph{Standard}:
9014GNU extension
9015
9016@item @emph{Standard}:
9017GNU extension
9018
9019@item @emph{Class}:
9020Subroutine, function
9021
9022@item @emph{Syntax}:
9023@multitable @columnfractions .80
9024@item @code{CALL KILL(PID, SIG [, STATUS])}
9025@item @code{STATUS = KILL(PID, SIG)}
9026@end multitable
9027
9028@item @emph{Arguments}:
9029@multitable @columnfractions .15 .70
9030@item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9031@item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9032@item @var{STATUS} @tab [Subroutine](Optional)
9033Shall be a scalar @code{INTEGER}.
9034Returns 0 on success; otherwise a system-specific error code is returned.
9035@item @var{STATUS} @tab [Function] The kind type parameter is that of
9036@code{pid}.
9037Returns 0 on success; otherwise a system-specific error code is returned.
9038@end multitable
9039
9040@item @emph{See also}:
9041@ref{ABORT}, @gol
9042@ref{EXIT}
9043@end table
9044
9045
9046@node KIND
9047@section @code{KIND} --- Kind of an entity
9048@fnindex KIND
9049@cindex kind
9050
9051@table @asis
9052@item @emph{Description}:
9053@code{KIND(X)} returns the kind value of the entity @var{X}.
9054
9055@item @emph{Standard}:
9056Fortran 95 and later
9057
9058@item @emph{Class}:
9059Inquiry function
9060
9061@item @emph{Syntax}:
9062@code{K = KIND(X)}
9063
9064@item @emph{Arguments}:
9065@multitable @columnfractions .15 .70
9066@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
9067@code{REAL}, @code{COMPLEX} or @code{CHARACTER}.  It may be scalar or
9068array valued.
9069@end multitable
9070
9071@item @emph{Return value}:
9072The return value is a scalar of type @code{INTEGER} and of the default
9073integer kind.
9074
9075@item @emph{Example}:
9076@smallexample
9077program test_kind
9078  integer,parameter :: kc = kind(' ')
9079  integer,parameter :: kl = kind(.true.)
9080
9081  print *, "The default character kind is ", kc
9082  print *, "The default logical kind is ", kl
9083end program test_kind
9084@end smallexample
9085
9086@end table
9087
9088
9089
9090@node LBOUND
9091@section @code{LBOUND} --- Lower dimension bounds of an array
9092@fnindex LBOUND
9093@cindex array, lower bound
9094
9095@table @asis
9096@item @emph{Description}:
9097Returns the lower bounds of an array, or a single lower bound
9098along the @var{DIM} dimension.
9099@item @emph{Standard}:
9100Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9101
9102@item @emph{Class}:
9103Inquiry function
9104
9105@item @emph{Syntax}:
9106@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
9107
9108@item @emph{Arguments}:
9109@multitable @columnfractions .15 .70
9110@item @var{ARRAY} @tab Shall be an array, of any type.
9111@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9112@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9113expression indicating the kind parameter of the result.
9114@end multitable
9115
9116@item @emph{Return value}:
9117The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9118@var{KIND} is absent, the return value is of default integer kind.
9119If @var{DIM} is absent, the result is an array of the lower bounds of
9120@var{ARRAY}.  If @var{DIM} is present, the result is a scalar
9121corresponding to the lower bound of the array along that dimension.  If
9122@var{ARRAY} is an expression rather than a whole array or array
9123structure component, or if it has a zero extent along the relevant
9124dimension, the lower bound is taken to be 1.
9125
9126@item @emph{See also}:
9127@ref{UBOUND}, @gol
9128@ref{LCOBOUND}
9129@end table
9130
9131
9132
9133@node LCOBOUND
9134@section @code{LCOBOUND} --- Lower codimension bounds of an array
9135@fnindex LCOBOUND
9136@cindex coarray, lower bound
9137
9138@table @asis
9139@item @emph{Description}:
9140Returns the lower bounds of a coarray, or a single lower cobound
9141along the @var{DIM} codimension.
9142@item @emph{Standard}:
9143Fortran 2008 and later
9144
9145@item @emph{Class}:
9146Inquiry function
9147
9148@item @emph{Syntax}:
9149@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
9150
9151@item @emph{Arguments}:
9152@multitable @columnfractions .15 .70
9153@item @var{ARRAY} @tab Shall be an coarray, of any type.
9154@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9155@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9156expression indicating the kind parameter of the result.
9157@end multitable
9158
9159@item @emph{Return value}:
9160The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9161@var{KIND} is absent, the return value is of default integer kind.
9162If @var{DIM} is absent, the result is an array of the lower cobounds of
9163@var{COARRAY}.  If @var{DIM} is present, the result is a scalar
9164corresponding to the lower cobound of the array along that codimension.
9165
9166@item @emph{See also}:
9167@ref{UCOBOUND}, @gol
9168@ref{LBOUND}
9169@end table
9170
9171
9172
9173@node LEADZ
9174@section @code{LEADZ} --- Number of leading zero bits of an integer
9175@fnindex LEADZ
9176@cindex zero bits
9177
9178@table @asis
9179@item @emph{Description}:
9180@code{LEADZ} returns the number of leading zero bits of an integer.
9181
9182@item @emph{Standard}:
9183Fortran 2008 and later
9184
9185@item @emph{Class}:
9186Elemental function
9187
9188@item @emph{Syntax}:
9189@code{RESULT = LEADZ(I)}
9190
9191@item @emph{Arguments}:
9192@multitable @columnfractions .15 .70
9193@item @var{I} @tab Shall be of type @code{INTEGER}.
9194@end multitable
9195
9196@item @emph{Return value}:
9197The type of the return value is the default @code{INTEGER}.
9198If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
9199
9200@item @emph{Example}:
9201@smallexample
9202PROGRAM test_leadz
9203  WRITE (*,*) BIT_SIZE(1)  ! prints 32
9204  WRITE (*,*) LEADZ(1)     ! prints 31
9205END PROGRAM
9206@end smallexample
9207
9208@item @emph{See also}:
9209@ref{BIT_SIZE}, @gol
9210@ref{TRAILZ}, @gol
9211@ref{POPCNT}, @gol
9212@ref{POPPAR}
9213@end table
9214
9215
9216
9217@node LEN
9218@section @code{LEN} --- Length of a character entity
9219@fnindex LEN
9220@cindex string, length
9221
9222@table @asis
9223@item @emph{Description}:
9224Returns the length of a character string.  If @var{STRING} is an array,
9225the length of an element of @var{STRING} is returned.  Note that
9226@var{STRING} need not be defined when this intrinsic is invoked, since
9227only the length, not the content, of @var{STRING} is needed.
9228
9229@item @emph{Standard}:
9230Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
9231
9232@item @emph{Class}:
9233Inquiry function
9234
9235@item @emph{Syntax}:
9236@code{L = LEN(STRING [, KIND])}
9237
9238@item @emph{Arguments}:
9239@multitable @columnfractions .15 .70
9240@item @var{STRING} @tab Shall be a scalar or array of type
9241@code{CHARACTER}, with @code{INTENT(IN)}
9242@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9243expression indicating the kind parameter of the result.
9244@end multitable
9245
9246@item @emph{Return value}:
9247The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9248@var{KIND} is absent, the return value is of default integer kind.
9249
9250
9251@item @emph{Specific names}:
9252@multitable @columnfractions .20 .23 .20 .33
9253@headitem Name               @tab Argument          @tab Return type       @tab Standard
9254@item @code{LEN(STRING)} @tab @code{CHARACTER}  @tab @code{INTEGER}    @tab Fortran 77 and later
9255@end multitable
9256
9257
9258@item @emph{See also}:
9259@ref{LEN_TRIM}, @gol
9260@ref{ADJUSTL}, @gol
9261@ref{ADJUSTR}
9262@end table
9263
9264
9265
9266@node LEN_TRIM
9267@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
9268@fnindex LEN_TRIM
9269@cindex string, length, without trailing whitespace
9270
9271@table @asis
9272@item @emph{Description}:
9273Returns the length of a character string, ignoring any trailing blanks.
9274
9275@item @emph{Standard}:
9276Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9277
9278@item @emph{Class}:
9279Elemental function
9280
9281@item @emph{Syntax}:
9282@code{RESULT = LEN_TRIM(STRING [, KIND])}
9283
9284@item @emph{Arguments}:
9285@multitable @columnfractions .15 .70
9286@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9287with @code{INTENT(IN)}
9288@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9289expression indicating the kind parameter of the result.
9290@end multitable
9291
9292@item @emph{Return value}:
9293The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9294@var{KIND} is absent, the return value is of default integer kind.
9295
9296@item @emph{See also}:
9297@ref{LEN}, @gol
9298@ref{ADJUSTL}, @gol
9299@ref{ADJUSTR}
9300@end table
9301
9302
9303
9304@node LGE
9305@section @code{LGE} --- Lexical greater than or equal
9306@fnindex LGE
9307@cindex lexical comparison of strings
9308@cindex string, comparison
9309
9310@table @asis
9311@item @emph{Description}:
9312Determines whether one string is lexically greater than or equal to
9313another string, where the two strings are interpreted as containing
9314ASCII character codes.  If the String A and String B are not the same
9315length, the shorter is compared as if spaces were appended to it to form
9316a value that has the same length as the longer.
9317
9318In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9319@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9320operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9321that the latter use the processor's character ordering (which is not
9322ASCII on some targets), whereas the former always use the ASCII
9323ordering.
9324
9325@item @emph{Standard}:
9326Fortran 77 and later
9327
9328@item @emph{Class}:
9329Elemental function
9330
9331@item @emph{Syntax}:
9332@code{RESULT = LGE(STRING_A, STRING_B)}
9333
9334@item @emph{Arguments}:
9335@multitable @columnfractions .15 .70
9336@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9337@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9338@end multitable
9339
9340@item @emph{Return value}:
9341Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9342otherwise, based on the ASCII ordering.
9343
9344@item @emph{Specific names}:
9345@multitable @columnfractions .34 .16 .17 .30
9346@headitem Name                           @tab Argument          @tab Return type       @tab Standard
9347@item @code{LGE(STRING_A,STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
9348@end multitable
9349
9350@item @emph{See also}:
9351@ref{LGT}, @gol
9352@ref{LLE}, @gol
9353@ref{LLT}
9354@end table
9355
9356
9357
9358@node LGT
9359@section @code{LGT} --- Lexical greater than
9360@fnindex LGT
9361@cindex lexical comparison of strings
9362@cindex string, comparison
9363
9364@table @asis
9365@item @emph{Description}:
9366Determines whether one string is lexically greater than another string,
9367where the two strings are interpreted as containing ASCII character
9368codes.  If the String A and String B are not the same length, the
9369shorter is compared as if spaces were appended to it to form a value
9370that has the same length as the longer.
9371
9372In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9373@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9374operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9375that the latter use the processor's character ordering (which is not
9376ASCII on some targets), whereas the former always use the ASCII
9377ordering.
9378
9379@item @emph{Standard}:
9380Fortran 77 and later
9381
9382@item @emph{Class}:
9383Elemental function
9384
9385@item @emph{Syntax}:
9386@code{RESULT = LGT(STRING_A, STRING_B)}
9387
9388@item @emph{Arguments}:
9389@multitable @columnfractions .15 .70
9390@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9391@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9392@end multitable
9393
9394@item @emph{Return value}:
9395Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9396otherwise, based on the ASCII ordering.
9397
9398@item @emph{Specific names}:
9399@multitable @columnfractions .34 .16 .17 .30
9400@headitem Name                           @tab Argument          @tab Return type       @tab Standard
9401@item @code{LGT(STRING_A,STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
9402@end multitable
9403
9404@item @emph{See also}:
9405@ref{LGE}, @gol
9406@ref{LLE}, @gol
9407@ref{LLT}
9408@end table
9409
9410
9411
9412@node LINK
9413@section @code{LINK} --- Create a hard link
9414@fnindex LINK
9415@cindex file system, create link
9416@cindex file system, hard link
9417
9418@table @asis
9419@item @emph{Description}:
9420Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9421character (@code{CHAR(0)}) can be used to mark the end of the names in
9422@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9423names are ignored.  If the @var{STATUS} argument is supplied, it
9424contains 0 on success or a nonzero error code upon return; see
9425@code{link(2)}.
9426
9427This intrinsic is provided in both subroutine and function forms;
9428however, only one form can be used in any given program unit.
9429
9430@item @emph{Standard}:
9431GNU extension
9432
9433@item @emph{Class}:
9434Subroutine, function
9435
9436@item @emph{Syntax}:
9437@multitable @columnfractions .80
9438@item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9439@item @code{STATUS = LINK(PATH1, PATH2)}
9440@end multitable
9441
9442@item @emph{Arguments}:
9443@multitable @columnfractions .15 .70
9444@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9445@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9446@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9447@end multitable
9448
9449@item @emph{See also}:
9450@ref{SYMLNK}, @gol
9451@ref{UNLINK}
9452@end table
9453
9454
9455
9456@node LLE
9457@section @code{LLE} --- Lexical less than or equal
9458@fnindex LLE
9459@cindex lexical comparison of strings
9460@cindex string, comparison
9461
9462@table @asis
9463@item @emph{Description}:
9464Determines whether one string is lexically less than or equal to another
9465string, where the two strings are interpreted as containing ASCII
9466character codes.  If the String A and String B are not the same length,
9467the shorter is compared as if spaces were appended to it to form a value
9468that has the same length as the longer.
9469
9470In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9471@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9472operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9473that the latter use the processor's character ordering (which is not
9474ASCII on some targets), whereas the former always use the ASCII
9475ordering.
9476
9477@item @emph{Standard}:
9478Fortran 77 and later
9479
9480@item @emph{Class}:
9481Elemental function
9482
9483@item @emph{Syntax}:
9484@code{RESULT = LLE(STRING_A, STRING_B)}
9485
9486@item @emph{Arguments}:
9487@multitable @columnfractions .15 .70
9488@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9489@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9490@end multitable
9491
9492@item @emph{Return value}:
9493Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9494otherwise, based on the ASCII ordering.
9495
9496@item @emph{Specific names}:
9497@multitable @columnfractions .34 .16 .17 .30
9498@headitem Name                           @tab Argument          @tab Return type       @tab Standard
9499@item @code{LLE(STRING_A,STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
9500@end multitable
9501
9502@item @emph{See also}:
9503@ref{LGE}, @gol
9504@ref{LGT}, @gol
9505@ref{LLT}
9506@end table
9507
9508
9509
9510@node LLT
9511@section @code{LLT} --- Lexical less than
9512@fnindex LLT
9513@cindex lexical comparison of strings
9514@cindex string, comparison
9515
9516@table @asis
9517@item @emph{Description}:
9518Determines whether one string is lexically less than another string,
9519where the two strings are interpreted as containing ASCII character
9520codes.  If the String A and String B are not the same length, the
9521shorter is compared as if spaces were appended to it to form a value
9522that has the same length as the longer.
9523
9524In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9525@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9526operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9527that the latter use the processor's character ordering (which is not
9528ASCII on some targets), whereas the former always use the ASCII
9529ordering.
9530
9531@item @emph{Standard}:
9532Fortran 77 and later
9533
9534@item @emph{Class}:
9535Elemental function
9536
9537@item @emph{Syntax}:
9538@code{RESULT = LLT(STRING_A, STRING_B)}
9539
9540@item @emph{Arguments}:
9541@multitable @columnfractions .15 .70
9542@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9543@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9544@end multitable
9545
9546@item @emph{Return value}:
9547Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9548otherwise, based on the ASCII ordering.
9549
9550@item @emph{Specific names}:
9551@multitable @columnfractions .34 .16 .17 .30
9552@headitem Name                           @tab Argument          @tab Return type       @tab Standard
9553@item @code{LLT(STRING_A,STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
9554@end multitable
9555
9556@item @emph{See also}:
9557@ref{LGE}, @gol
9558@ref{LGT}, @gol
9559@ref{LLE}
9560@end table
9561
9562
9563
9564@node LNBLNK
9565@section @code{LNBLNK} --- Index of the last non-blank character in a string
9566@fnindex LNBLNK
9567@cindex string, find non-blank character
9568
9569@table @asis
9570@item @emph{Description}:
9571Returns the length of a character string, ignoring any trailing blanks.
9572This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9573included for backwards compatibility.
9574
9575@item @emph{Standard}:
9576GNU extension
9577
9578@item @emph{Class}:
9579Elemental function
9580
9581@item @emph{Syntax}:
9582@code{RESULT = LNBLNK(STRING)}
9583
9584@item @emph{Arguments}:
9585@multitable @columnfractions .15 .70
9586@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9587with @code{INTENT(IN)}
9588@end multitable
9589
9590@item @emph{Return value}:
9591The return value is of @code{INTEGER(kind=4)} type.
9592
9593@item @emph{See also}:
9594@ref{INDEX intrinsic}, @gol
9595@ref{LEN_TRIM}
9596@end table
9597
9598
9599
9600@node LOC
9601@section @code{LOC} --- Returns the address of a variable
9602@fnindex LOC
9603@cindex location of a variable in memory
9604
9605@table @asis
9606@item @emph{Description}:
9607@code{LOC(X)} returns the address of @var{X} as an integer.
9608
9609@item @emph{Standard}:
9610GNU extension
9611
9612@item @emph{Class}:
9613Inquiry function
9614
9615@item @emph{Syntax}:
9616@code{RESULT = LOC(X)}
9617
9618@item @emph{Arguments}:
9619@multitable @columnfractions .15 .70
9620@item @var{X} @tab Variable of any type.
9621@end multitable
9622
9623@item @emph{Return value}:
9624The return value is of type @code{INTEGER}, with a @code{KIND}
9625corresponding to the size (in bytes) of a memory address on the target
9626machine.
9627
9628@item @emph{Example}:
9629@smallexample
9630program test_loc
9631  integer :: i
9632  real :: r
9633  i = loc(r)
9634  print *, i
9635end program test_loc
9636@end smallexample
9637@end table
9638
9639
9640
9641@node LOG
9642@section @code{LOG} --- Natural logarithm function
9643@fnindex LOG
9644@fnindex ALOG
9645@fnindex DLOG
9646@fnindex CLOG
9647@fnindex ZLOG
9648@fnindex CDLOG
9649@cindex exponential function, inverse
9650@cindex logarithm function
9651@cindex natural logarithm function
9652
9653@table @asis
9654@item @emph{Description}:
9655@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9656logarithm to the base @math{e}.
9657
9658@item @emph{Standard}:
9659Fortran 77 and later, has GNU extensions
9660
9661@item @emph{Class}:
9662Elemental function
9663
9664@item @emph{Syntax}:
9665@code{RESULT = LOG(X)}
9666
9667@item @emph{Arguments}:
9668@multitable @columnfractions .15 .70
9669@item @var{X} @tab The type shall be @code{REAL} or
9670@code{COMPLEX}.
9671@end multitable
9672
9673@item @emph{Return value}:
9674The return value is of type @code{REAL} or @code{COMPLEX}.
9675The kind type parameter is the same as @var{X}.
9676If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9677@math{-\pi < \omega \leq \pi}.
9678
9679@item @emph{Example}:
9680@smallexample
9681program test_log
9682  real(8) :: x = 2.7182818284590451_8
9683  complex :: z = (1.0, 2.0)
9684  x = log(x)    ! will yield (approximately) 1
9685  z = log(z)
9686end program test_log
9687@end smallexample
9688
9689@item @emph{Specific names}:
9690@multitable @columnfractions .20 .23 .20 .33
9691@headitem Name            @tab Argument          @tab Return type       @tab Standard
9692@item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 or later
9693@item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 or later
9694@item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 77 or later
9695@item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
9696@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
9697@end multitable
9698@end table
9699
9700
9701
9702@node LOG10
9703@section @code{LOG10} --- Base 10 logarithm function
9704@fnindex LOG10
9705@fnindex ALOG10
9706@fnindex DLOG10
9707@cindex exponential function, inverse
9708@cindex logarithm function with base 10
9709@cindex base 10 logarithm function
9710
9711@table @asis
9712@item @emph{Description}:
9713@code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9714
9715@item @emph{Standard}:
9716Fortran 77 and later
9717
9718@item @emph{Class}:
9719Elemental function
9720
9721@item @emph{Syntax}:
9722@code{RESULT = LOG10(X)}
9723
9724@item @emph{Arguments}:
9725@multitable @columnfractions .15 .70
9726@item @var{X} @tab The type shall be @code{REAL}.
9727@end multitable
9728
9729@item @emph{Return value}:
9730The return value is of type @code{REAL} or @code{COMPLEX}.
9731The kind type parameter is the same as @var{X}.
9732
9733@item @emph{Example}:
9734@smallexample
9735program test_log10
9736  real(8) :: x = 10.0_8
9737  x = log10(x)
9738end program test_log10
9739@end smallexample
9740
9741@item @emph{Specific names}:
9742@multitable @columnfractions .20 .23 .20 .33
9743@headitem Name            @tab Argument          @tab Return type       @tab Standard
9744@item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
9745@item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
9746@end multitable
9747@end table
9748
9749
9750
9751@node LOG_GAMMA
9752@section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9753@fnindex LOG_GAMMA
9754@fnindex LGAMMA
9755@fnindex ALGAMA
9756@fnindex DLGAMA
9757@cindex Gamma function, logarithm of
9758
9759@table @asis
9760@item @emph{Description}:
9761@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9762of the Gamma (@math{\Gamma}) function.
9763
9764@item @emph{Standard}:
9765Fortran 2008 and later
9766
9767@item @emph{Class}:
9768Elemental function
9769
9770@item @emph{Syntax}:
9771@code{X = LOG_GAMMA(X)}
9772
9773@item @emph{Arguments}:
9774@multitable @columnfractions .15 .70
9775@item @var{X} @tab Shall be of type @code{REAL} and neither zero
9776nor a negative integer.
9777@end multitable
9778
9779@item @emph{Return value}:
9780The return value is of type @code{REAL} of the same kind as @var{X}.
9781
9782@item @emph{Example}:
9783@smallexample
9784program test_log_gamma
9785  real :: x = 1.0
9786  x = lgamma(x) ! returns 0.0
9787end program test_log_gamma
9788@end smallexample
9789
9790@item @emph{Specific names}:
9791@multitable @columnfractions .20 .23 .20 .33
9792@headitem Name             @tab Argument         @tab Return type       @tab Standard
9793@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU extension
9794@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU extension
9795@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU extension
9796@end multitable
9797
9798@item @emph{See also}:
9799Gamma function: @gol
9800@ref{GAMMA}
9801@end table
9802
9803
9804
9805@node LOGICAL
9806@section @code{LOGICAL} --- Convert to logical type
9807@fnindex LOGICAL
9808@cindex conversion, to logical
9809
9810@table @asis
9811@item @emph{Description}:
9812Converts one kind of @code{LOGICAL} variable to another.
9813
9814@item @emph{Standard}:
9815Fortran 90 and later
9816
9817@item @emph{Class}:
9818Elemental function
9819
9820@item @emph{Syntax}:
9821@code{RESULT = LOGICAL(L [, KIND])}
9822
9823@item @emph{Arguments}:
9824@multitable @columnfractions .15 .70
9825@item @var{L}    @tab The type shall be @code{LOGICAL}.
9826@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9827expression indicating the kind parameter of the result.
9828@end multitable
9829
9830@item @emph{Return value}:
9831The return value is a @code{LOGICAL} value equal to @var{L}, with a
9832kind corresponding to @var{KIND}, or of the default logical kind if
9833@var{KIND} is not given.
9834
9835@item @emph{See also}:
9836@ref{INT}, @gol
9837@ref{REAL}, @gol
9838@ref{CMPLX}
9839@end table
9840
9841
9842
9843@node LSHIFT
9844@section @code{LSHIFT} --- Left shift bits
9845@fnindex LSHIFT
9846@cindex bits, shift left
9847
9848@table @asis
9849@item @emph{Description}:
9850@code{LSHIFT} returns a value corresponding to @var{I} with all of the
9851bits shifted left by @var{SHIFT} places.  @var{SHIFT} shall be
9852nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
9853the result value is undefined.  Bits shifted out from the left end are
9854lost; zeros are shifted in from the opposite end.
9855
9856This function has been superseded by the @code{ISHFT} intrinsic, which
9857is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9858which is standard in Fortran 2008 and later.
9859
9860@item @emph{Standard}:
9861GNU extension
9862
9863@item @emph{Class}:
9864Elemental function
9865
9866@item @emph{Syntax}:
9867@code{RESULT = LSHIFT(I, SHIFT)}
9868
9869@item @emph{Arguments}:
9870@multitable @columnfractions .15 .70
9871@item @var{I} @tab The type shall be @code{INTEGER}.
9872@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9873@end multitable
9874
9875@item @emph{Return value}:
9876The return value is of type @code{INTEGER} and of the same kind as
9877@var{I}.
9878
9879@item @emph{See also}:
9880@ref{ISHFT}, @gol
9881@ref{ISHFTC}, @gol
9882@ref{RSHIFT}, @gol
9883@ref{SHIFTA}, @gol
9884@ref{SHIFTL}, @gol
9885@ref{SHIFTR}
9886@end table
9887
9888
9889
9890@node LSTAT
9891@section @code{LSTAT} --- Get file status
9892@fnindex LSTAT
9893@cindex file system, file status
9894
9895@table @asis
9896@item @emph{Description}:
9897@code{LSTAT} is identical to @ref{STAT}, except that if path is a
9898symbolic link, then the link itself is statted, not the file that it
9899refers to.
9900
9901The elements in @code{VALUES} are the same as described by @ref{STAT}.
9902
9903This intrinsic is provided in both subroutine and function forms;
9904however, only one form can be used in any given program unit.
9905
9906@item @emph{Standard}:
9907GNU extension
9908
9909@item @emph{Class}:
9910Subroutine, function
9911
9912@item @emph{Syntax}:
9913@multitable @columnfractions .80
9914@item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9915@item @code{STATUS = LSTAT(NAME, VALUES)}
9916@end multitable
9917
9918@item @emph{Arguments}:
9919@multitable @columnfractions .15 .70
9920@item @var{NAME}   @tab The type shall be @code{CHARACTER} of the default
9921kind, a valid path within the file system.
9922@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9923@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9924Returns 0 on success and a system specific error code otherwise.
9925@end multitable
9926
9927@item @emph{Example}:
9928See @ref{STAT} for an example.
9929
9930@item @emph{See also}:
9931To stat an open file: @gol
9932@ref{FSTAT} @gol
9933To stat a file: @gol
9934@ref{STAT}
9935@end table
9936
9937
9938
9939@node LTIME
9940@section @code{LTIME} --- Convert time to local time info
9941@fnindex LTIME
9942@cindex time, conversion to local time info
9943
9944@table @asis
9945@item @emph{Description}:
9946Given a system time value @var{TIME} (as provided by the @ref{TIME}
9947intrinsic), fills @var{VALUES} with values extracted from it appropriate
9948to the local time zone using @code{localtime(3)}.
9949
9950This intrinsic routine is provided for backwards compatibility with
9951GNU Fortran 77.  In new code, programmers should consider the use of
9952the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
9953standard.
9954
9955@item @emph{Standard}:
9956GNU extension
9957
9958@item @emph{Class}:
9959Subroutine
9960
9961@item @emph{Syntax}:
9962@code{CALL LTIME(TIME, VALUES)}
9963
9964@item @emph{Arguments}:
9965@multitable @columnfractions .15 .70
9966@item @var{TIME}  @tab An @code{INTEGER} scalar expression
9967corresponding to a system time, with @code{INTENT(IN)}.
9968@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9969with @code{INTENT(OUT)}.
9970@end multitable
9971
9972@item @emph{Return value}:
9973The elements of @var{VALUES} are assigned as follows:
9974@enumerate
9975@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9976seconds
9977@item Minutes after the hour, range 0--59
9978@item Hours past midnight, range 0--23
9979@item Day of month, range 1--31
9980@item Number of months since January, range 0--11
9981@item Years since 1900
9982@item Number of days since Sunday, range 0--6
9983@item Days since January 1, range 0--365
9984@item Daylight savings indicator: positive if daylight savings is in
9985effect, zero if not, and negative if the information is not available.
9986@end enumerate
9987
9988@item @emph{See also}:
9989@ref{DATE_AND_TIME}, @gol
9990@ref{CTIME}, @gol
9991@ref{GMTIME}, @gol
9992@ref{TIME}, @gol
9993@ref{TIME8}
9994@end table
9995
9996
9997
9998@node MALLOC
9999@section @code{MALLOC} --- Allocate dynamic memory
10000@fnindex MALLOC
10001@cindex pointer, cray
10002
10003@table @asis
10004@item @emph{Description}:
10005@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
10006returns the address of the allocated memory. The @code{MALLOC} intrinsic
10007is an extension intended to be used with Cray pointers, and is provided
10008in GNU Fortran to allow the user to compile legacy code. For new code
10009using Fortran 95 pointers, the memory allocation intrinsic is
10010@code{ALLOCATE}.
10011
10012@item @emph{Standard}:
10013GNU extension
10014
10015@item @emph{Class}:
10016Function
10017
10018@item @emph{Syntax}:
10019@code{PTR = MALLOC(SIZE)}
10020
10021@item @emph{Arguments}:
10022@multitable @columnfractions .15 .70
10023@item @var{SIZE} @tab The type shall be @code{INTEGER}.
10024@end multitable
10025
10026@item @emph{Return value}:
10027The return value is of type @code{INTEGER(K)}, with @var{K} such that
10028variables of type @code{INTEGER(K)} have the same size as
10029C pointers (@code{sizeof(void *)}).
10030
10031@item @emph{Example}:
10032The following example demonstrates the use of @code{MALLOC} and
10033@code{FREE} with Cray pointers.
10034
10035@smallexample
10036program test_malloc
10037  implicit none
10038  integer i
10039  real*8 x(*), z
10040  pointer(ptr_x,x)
10041
10042  ptr_x = malloc(20*8)
10043  do i = 1, 20
10044    x(i) = sqrt(1.0d0 / i)
10045  end do
10046  z = 0
10047  do i = 1, 20
10048    z = z + x(i)
10049    print *, z
10050  end do
10051  call free(ptr_x)
10052end program test_malloc
10053@end smallexample
10054
10055@item @emph{See also}:
10056@ref{FREE}
10057@end table
10058
10059
10060
10061@node MASKL
10062@section @code{MASKL} --- Left justified mask
10063@fnindex MASKL
10064@cindex mask, left justified
10065
10066@table @asis
10067@item @emph{Description}:
10068@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
10069remaining bits set to 0.
10070
10071@item @emph{Standard}:
10072Fortran 2008 and later
10073
10074@item @emph{Class}:
10075Elemental function
10076
10077@item @emph{Syntax}:
10078@code{RESULT = MASKL(I[, KIND])}
10079
10080@item @emph{Arguments}:
10081@multitable @columnfractions .15 .70
10082@item @var{I} @tab Shall be of type @code{INTEGER}.
10083@item @var{KIND} @tab Shall be a scalar constant expression of type
10084@code{INTEGER}.
10085@end multitable
10086
10087@item @emph{Return value}:
10088The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10089specifies the kind value of the return type; otherwise, it is of the
10090default integer kind.
10091
10092@item @emph{See also}:
10093@ref{MASKR}
10094@end table
10095
10096
10097
10098@node MASKR
10099@section @code{MASKR} --- Right justified mask
10100@fnindex MASKR
10101@cindex mask, right justified
10102
10103@table @asis
10104@item @emph{Description}:
10105@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
10106remaining bits set to 0.
10107
10108@item @emph{Standard}:
10109Fortran 2008 and later
10110
10111@item @emph{Class}:
10112Elemental function
10113
10114@item @emph{Syntax}:
10115@code{RESULT = MASKR(I[, KIND])}
10116
10117@item @emph{Arguments}:
10118@multitable @columnfractions .15 .70
10119@item @var{I} @tab Shall be of type @code{INTEGER}.
10120@item @var{KIND} @tab Shall be a scalar constant expression of type
10121@code{INTEGER}.
10122@end multitable
10123
10124@item @emph{Return value}:
10125The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10126specifies the kind value of the return type; otherwise, it is of the
10127default integer kind.
10128
10129@item @emph{See also}:
10130@ref{MASKL}
10131@end table
10132
10133
10134
10135@node MATMUL
10136@section @code{MATMUL} --- matrix multiplication
10137@fnindex MATMUL
10138@cindex matrix multiplication
10139@cindex product, matrix
10140
10141@table @asis
10142@item @emph{Description}:
10143Performs a matrix multiplication on numeric or logical arguments.
10144
10145@item @emph{Standard}:
10146Fortran 90 and later
10147
10148@item @emph{Class}:
10149Transformational function
10150
10151@item @emph{Syntax}:
10152@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
10153
10154@item @emph{Arguments}:
10155@multitable @columnfractions .15 .70
10156@item @var{MATRIX_A} @tab An array of @code{INTEGER},
10157@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
10158one or two.
10159@item @var{MATRIX_B} @tab An array of @code{INTEGER},
10160@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
10161type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
10162or two, and the first (or only) dimension of @var{MATRIX_B} shall be
10163equal to the last (or only) dimension of @var{MATRIX_A}.
10164@var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
10165@end multitable
10166
10167@item @emph{Return value}:
10168The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
10169kind of the result follow the usual type and kind promotion rules, as
10170for the @code{*} or @code{.AND.} operators.
10171@end table
10172
10173
10174
10175@node MAX
10176@section @code{MAX} --- Maximum value of an argument list
10177@fnindex MAX
10178@fnindex MAX0
10179@fnindex AMAX0
10180@fnindex MAX1
10181@fnindex AMAX1
10182@fnindex DMAX1
10183@cindex maximum value
10184
10185@table @asis
10186@item @emph{Description}:
10187Returns the argument with the largest (most positive) value.
10188
10189@item @emph{Standard}:
10190Fortran 77 and later
10191
10192@item @emph{Class}:
10193Elemental function
10194
10195@item @emph{Syntax}:
10196@code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
10197
10198@item @emph{Arguments}:
10199@multitable @columnfractions .15 .70
10200@item @var{A1}          @tab The type shall be @code{INTEGER} or
10201@code{REAL}.
10202@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10203as @var{A1}.  (As a GNU extension, arguments of different kinds are
10204permitted.)
10205@end multitable
10206
10207@item @emph{Return value}:
10208The return value corresponds to the maximum value among the arguments,
10209and has the same type and kind as the first argument.
10210
10211@item @emph{Specific names}:
10212@multitable @columnfractions .20 .23 .20 .33
10213@headitem Name             @tab Argument             @tab Return type         @tab Standard
10214@item @code{MAX0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
10215@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
10216@item @code{MAX1(A1)}  @tab @code{REAL A1}       @tab @code{INT(MAX(X))}  @tab Fortran 77 and later
10217@item @code{AMAX1(A1)} @tab @code{REAL(4) A1}    @tab @code{REAL(4)}      @tab Fortran 77 and later
10218@item @code{DMAX1(A1)} @tab @code{REAL(8) A1}    @tab @code{REAL(8)}      @tab Fortran 77 and later
10219@end multitable
10220
10221@item @emph{See also}:
10222@ref{MAXLOC} @gol
10223@ref{MAXVAL}, @gol
10224@ref{MIN}
10225@end table
10226
10227
10228
10229@node MAXEXPONENT
10230@section @code{MAXEXPONENT} --- Maximum exponent of a real kind
10231@fnindex MAXEXPONENT
10232@cindex model representation, maximum exponent
10233
10234@table @asis
10235@item @emph{Description}:
10236@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
10237type of @code{X}.
10238
10239@item @emph{Standard}:
10240Fortran 90 and later
10241
10242@item @emph{Class}:
10243Inquiry function
10244
10245@item @emph{Syntax}:
10246@code{RESULT = MAXEXPONENT(X)}
10247
10248@item @emph{Arguments}:
10249@multitable @columnfractions .15 .70
10250@item @var{X} @tab Shall be of type @code{REAL}.
10251@end multitable
10252
10253@item @emph{Return value}:
10254The return value is of type @code{INTEGER} and of the default integer
10255kind.
10256
10257@item @emph{Example}:
10258@smallexample
10259program exponents
10260  real(kind=4) :: x
10261  real(kind=8) :: y
10262
10263  print *, minexponent(x), maxexponent(x)
10264  print *, minexponent(y), maxexponent(y)
10265end program exponents
10266@end smallexample
10267@end table
10268
10269
10270
10271@node MAXLOC
10272@section @code{MAXLOC} --- Location of the maximum value within an array
10273@fnindex MAXLOC
10274@cindex array, location of maximum element
10275
10276@table @asis
10277@item @emph{Description}:
10278Determines the location of the element in the array with the maximum
10279value, or, if the @var{DIM} argument is supplied, determines the
10280locations of the maximum element along each row of the array in the
10281@var{DIM} direction.  If @var{MASK} is present, only the elements for
10282which @var{MASK} is @code{.TRUE.} are considered.  If more than one
10283element in the array has the maximum value, the location returned is
10284that of the first such element in array element order if the
10285@var{BACK} is not present, or is false; if @var{BACK} is true, the location
10286returned is that of the last such element. If the array has zero
10287size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10288the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
10289and all of the elements of @var{MASK} along a given row are zero, the
10290result value for that row is zero.
10291
10292@item @emph{Standard}:
10293Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10294@var{KIND} argument are available in Fortran 2003 and later.
10295The @var{BACK} argument is available in Fortran 2008 and later.
10296
10297@item @emph{Class}:
10298Transformational function
10299
10300@item @emph{Syntax}:
10301@multitable @columnfractions .80
10302@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10303@item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])}
10304@end multitable
10305
10306@item @emph{Arguments}:
10307@multitable @columnfractions .15 .70
10308@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10309@code{REAL}.
10310@item @var{DIM}   @tab (Optional) Shall be a scalar of type
10311@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10312inclusive.  It may not be an optional dummy argument.
10313@item @var{MASK}  @tab Shall be of type @code{LOGICAL},
10314and conformable with @var{ARRAY}.
10315@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10316expression indicating the kind parameter of the result.
10317@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10318@end multitable
10319
10320@item @emph{Return value}:
10321If @var{DIM} is absent, the result is a rank-one array with a length
10322equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
10323is an array with a rank one less than the rank of @var{ARRAY}, and a
10324size corresponding to the size of @var{ARRAY} with the @var{DIM}
10325dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
10326of one, the result is a scalar.   If the optional argument @var{KIND}
10327is present, the result is an integer of kind @var{KIND}, otherwise it
10328is of default kind.
10329
10330@item @emph{See also}:
10331@ref{FINDLOC}, @gol
10332@ref{MAX}, @gol
10333@ref{MAXVAL}
10334@end table
10335
10336
10337
10338@node MAXVAL
10339@section @code{MAXVAL} --- Maximum value of an array
10340@fnindex MAXVAL
10341@cindex array, maximum value
10342@cindex maximum value
10343
10344@table @asis
10345@item @emph{Description}:
10346Determines the maximum value of the elements in an array value, or, if
10347the @var{DIM} argument is supplied, determines the maximum value along
10348each row of the array in the @var{DIM} direction.  If @var{MASK} is
10349present, only the elements for which @var{MASK} is @code{.TRUE.} are
10350considered.  If the array has zero size, or all of the elements of
10351@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10352if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10353type.
10354
10355@item @emph{Standard}:
10356Fortran 90 and later
10357
10358@item @emph{Class}:
10359Transformational function
10360
10361@item @emph{Syntax}:
10362@multitable @columnfractions .80
10363@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10364@item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10365@end multitable
10366
10367@item @emph{Arguments}:
10368@multitable @columnfractions .15 .70
10369@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10370@code{REAL}.
10371@item @var{DIM}   @tab (Optional) Shall be a scalar of type
10372@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10373inclusive.  It may not be an optional dummy argument.
10374@item @var{MASK}  @tab (Optional) Shall be of type @code{LOGICAL},
10375and conformable with @var{ARRAY}.
10376@end multitable
10377
10378@item @emph{Return value}:
10379If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10380is a scalar.  If @var{DIM} is present, the result is an array with a
10381rank one less than the rank of @var{ARRAY}, and a size corresponding to
10382the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
10383cases, the result is of the same type and kind as @var{ARRAY}.
10384
10385@item @emph{See also}:
10386@ref{MAX}, @gol
10387@ref{MAXLOC}
10388@end table
10389
10390
10391
10392@node MCLOCK
10393@section @code{MCLOCK} --- Time function
10394@fnindex MCLOCK
10395@cindex time, clock ticks
10396@cindex clock ticks
10397
10398@table @asis
10399@item @emph{Description}:
10400Returns the number of clock ticks since the start of the process, based
10401on the function @code{clock(3)} in the C standard library.
10402
10403This intrinsic is not fully portable, such as to systems with 32-bit
10404@code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10405the values returned by this intrinsic might be, or become, negative, or
10406numerically less than previous values, during a single run of the
10407compiled program.
10408
10409@item @emph{Standard}:
10410GNU extension
10411
10412@item @emph{Class}:
10413Function
10414
10415@item @emph{Syntax}:
10416@code{RESULT = MCLOCK()}
10417
10418@item @emph{Return value}:
10419The return value is a scalar of type @code{INTEGER(4)}, equal to the
10420number of clock ticks since the start of the process, or @code{-1} if
10421the system does not support @code{clock(3)}.
10422
10423@item @emph{See also}:
10424@ref{CTIME}, @gol
10425@ref{GMTIME}, @gol
10426@ref{LTIME}, @gol
10427@ref{MCLOCK}, @gol
10428@ref{TIME}
10429@end table
10430
10431
10432
10433@node MCLOCK8
10434@section @code{MCLOCK8} --- Time function (64-bit)
10435@fnindex MCLOCK8
10436@cindex time, clock ticks
10437@cindex clock ticks
10438
10439@table @asis
10440@item @emph{Description}:
10441Returns the number of clock ticks since the start of the process, based
10442on the function @code{clock(3)} in the C standard library.
10443
10444@emph{Warning:} this intrinsic does not increase the range of the timing
10445values over that returned by @code{clock(3)}. On a system with a 32-bit
10446@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10447it is converted to a 64-bit @code{INTEGER(8)} value. That means
10448overflows of the 32-bit value can still occur. Therefore, the values
10449returned by this intrinsic might be or become negative or numerically
10450less than previous values during a single run of the compiled program.
10451
10452@item @emph{Standard}:
10453GNU extension
10454
10455@item @emph{Class}:
10456Function
10457
10458@item @emph{Syntax}:
10459@code{RESULT = MCLOCK8()}
10460
10461@item @emph{Return value}:
10462The return value is a scalar of type @code{INTEGER(8)}, equal to the
10463number of clock ticks since the start of the process, or @code{-1} if
10464the system does not support @code{clock(3)}.
10465
10466@item @emph{See also}:
10467@ref{CTIME}, @gol
10468@ref{GMTIME}, @gol
10469@ref{LTIME}, @gol
10470@ref{MCLOCK}, @gol
10471@ref{TIME8}
10472@end table
10473
10474
10475
10476@node MERGE
10477@section @code{MERGE} --- Merge variables
10478@fnindex MERGE
10479@cindex array, merge arrays
10480@cindex array, combine arrays
10481
10482@table @asis
10483@item @emph{Description}:
10484Select values from two arrays according to a logical mask.  The result
10485is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10486@var{FSOURCE} if it is @code{.FALSE.}.
10487
10488@item @emph{Standard}:
10489Fortran 90 and later
10490
10491@item @emph{Class}:
10492Elemental function
10493
10494@item @emph{Syntax}:
10495@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10496
10497@item @emph{Arguments}:
10498@multitable @columnfractions .15 .70
10499@item @var{TSOURCE} @tab May be of any type.
10500@item @var{FSOURCE} @tab Shall be of the same type and type parameters
10501as @var{TSOURCE}.
10502@item @var{MASK}    @tab Shall be of type @code{LOGICAL}.
10503@end multitable
10504
10505@item @emph{Return value}:
10506The result is of the same type and type parameters as @var{TSOURCE}.
10507
10508@end table
10509
10510
10511
10512@node MERGE_BITS
10513@section @code{MERGE_BITS} --- Merge of bits under mask
10514@fnindex MERGE_BITS
10515@cindex bits, merge
10516
10517@table @asis
10518@item @emph{Description}:
10519@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10520as determined by the mask.  The i-th bit of the result is equal to the
10521i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10522the i-th bit of @var{J} otherwise.
10523
10524@item @emph{Standard}:
10525Fortran 2008 and later
10526
10527@item @emph{Class}:
10528Elemental function
10529
10530@item @emph{Syntax}:
10531@code{RESULT = MERGE_BITS(I, J, MASK)}
10532
10533@item @emph{Arguments}:
10534@multitable @columnfractions .15 .70
10535@item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant.
10536@item @var{J} @tab Shall be of type @code{INTEGER} with the same
10537kind type parameter as @var{I} or a boz-literal-constant.
10538@var{I} and @var{J} shall not both be boz-literal-constants.
10539@item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant
10540and of the same kind as @var{I}.
10541@end multitable
10542
10543@item @emph{Return value}:
10544The result is of the same type and kind as @var{I}.
10545
10546@end table
10547
10548
10549
10550@node MIN
10551@section @code{MIN} --- Minimum value of an argument list
10552@fnindex MIN
10553@fnindex MIN0
10554@fnindex AMIN0
10555@fnindex MIN1
10556@fnindex AMIN1
10557@fnindex DMIN1
10558@cindex minimum value
10559
10560@table @asis
10561@item @emph{Description}:
10562Returns the argument with the smallest (most negative) value.
10563
10564@item @emph{Standard}:
10565Fortran 77 and later
10566
10567@item @emph{Class}:
10568Elemental function
10569
10570@item @emph{Syntax}:
10571@code{RESULT = MIN(A1, A2 [, A3, ...])}
10572
10573@item @emph{Arguments}:
10574@multitable @columnfractions .15 .70
10575@item @var{A1}          @tab The type shall be @code{INTEGER} or
10576@code{REAL}.
10577@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10578as @var{A1}.  (As a GNU extension, arguments of different kinds are
10579permitted.)
10580@end multitable
10581
10582@item @emph{Return value}:
10583The return value corresponds to the minimum value among the arguments,
10584and has the same type and kind as the first argument.
10585
10586@item @emph{Specific names}:
10587@multitable @columnfractions .20 .23 .20 .33
10588@headitem Name              @tab Argument             @tab Return type        @tab Standard
10589@item @code{MIN0(A1)}   @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}  @tab Fortran 77 and later
10590@item @code{AMIN0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{REAL(4)}     @tab Fortran 77 and later
10591@item @code{MIN1(A1)}   @tab @code{REAL A1}       @tab @code{INTEGER(4)}  @tab Fortran 77 and later
10592@item @code{AMIN1(A1)}  @tab @code{REAL(4) A1}    @tab @code{REAL(4)}     @tab Fortran 77 and later
10593@item @code{DMIN1(A1)}  @tab @code{REAL(8) A1}    @tab @code{REAL(8)}     @tab Fortran 77 and later
10594@end multitable
10595
10596@item @emph{See also}:
10597@ref{MAX}, @gol
10598@ref{MINLOC}, @gol
10599@ref{MINVAL}
10600@end table
10601
10602
10603
10604@node MINEXPONENT
10605@section @code{MINEXPONENT} --- Minimum exponent of a real kind
10606@fnindex MINEXPONENT
10607@cindex model representation, minimum exponent
10608
10609@table @asis
10610@item @emph{Description}:
10611@code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10612type of @code{X}.
10613
10614@item @emph{Standard}:
10615Fortran 90 and later
10616
10617@item @emph{Class}:
10618Inquiry function
10619
10620@item @emph{Syntax}:
10621@code{RESULT = MINEXPONENT(X)}
10622
10623@item @emph{Arguments}:
10624@multitable @columnfractions .15 .70
10625@item @var{X} @tab Shall be of type @code{REAL}.
10626@end multitable
10627
10628@item @emph{Return value}:
10629The return value is of type @code{INTEGER} and of the default integer
10630kind.
10631
10632@item @emph{Example}:
10633See @code{MAXEXPONENT} for an example.
10634@end table
10635
10636
10637
10638@node MINLOC
10639@section @code{MINLOC} --- Location of the minimum value within an array
10640@fnindex MINLOC
10641@cindex array, location of minimum element
10642
10643@table @asis
10644@item @emph{Description}:
10645Determines the location of the element in the array with the minimum
10646value, or, if the @var{DIM} argument is supplied, determines the
10647locations of the minimum element along each row of the array in the
10648@var{DIM} direction.  If @var{MASK} is present, only the elements for
10649which @var{MASK} is @code{.TRUE.} are considered.  If more than one
10650element in the array has the minimum value, the location returned is
10651that of the first such element in array element order if the
10652@var{BACK} is not present, or is false; if @var{BACK} is true, the location
10653returned is that of the last such element.  If the array has
10654zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10655the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
10656and all of the elements of @var{MASK} along a given row are zero, the
10657result value for that row is zero.
10658
10659@item @emph{Standard}:
10660Fortran 90 and later; @var{ARRAY} of @code{CHARACTER} and the
10661@var{KIND} argument are available in Fortran 2003 and later.
10662The @var{BACK} argument is available in Fortran 2008 and later.
10663
10664@item @emph{Class}:
10665Transformational function
10666
10667@item @emph{Syntax}:
10668@multitable @columnfractions .80
10669@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10670@item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])}
10671@end multitable
10672
10673@item @emph{Arguments}:
10674@multitable @columnfractions .15 .70
10675@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10676@code{REAL} or @code{CHARACTER}.
10677@item @var{DIM}   @tab (Optional) Shall be a scalar of type
10678@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10679inclusive.  It may not be an optional dummy argument.
10680@item @var{MASK}  @tab Shall be of type @code{LOGICAL},
10681and conformable with @var{ARRAY}.
10682@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10683expression indicating the kind parameter of the result.
10684@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10685@end multitable
10686
10687@item @emph{Return value}:
10688If @var{DIM} is absent, the result is a rank-one array with a length
10689equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
10690is an array with a rank one less than the rank of @var{ARRAY}, and a
10691size corresponding to the size of @var{ARRAY} with the @var{DIM}
10692dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
10693of one, the result is a scalar.  If the optional argument @var{KIND}
10694is present, the result is an integer of kind @var{KIND}, otherwise it
10695is of default kind.
10696
10697@item @emph{See also}:
10698@ref{FINDLOC}, @gol
10699@ref{MIN}, @gol
10700@ref{MINVAL}
10701@end table
10702
10703
10704
10705@node MINVAL
10706@section @code{MINVAL} --- Minimum value of an array
10707@fnindex MINVAL
10708@cindex array, minimum value
10709@cindex minimum value
10710
10711@table @asis
10712@item @emph{Description}:
10713Determines the minimum value of the elements in an array value, or, if
10714the @var{DIM} argument is supplied, determines the minimum value along
10715each row of the array in the @var{DIM} direction.  If @var{MASK} is
10716present, only the elements for which @var{MASK} is @code{.TRUE.} are
10717considered.  If the array has zero size, or all of the elements of
10718@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10719@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10720@var{ARRAY} is of character type.
10721
10722@item @emph{Standard}:
10723Fortran 90 and later
10724
10725@item @emph{Class}:
10726Transformational function
10727
10728@item @emph{Syntax}:
10729@multitable @columnfractions .80
10730@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10731@item @code{RESULT = MINVAL(ARRAY [, MASK])}
10732@end multitable
10733
10734@item @emph{Arguments}:
10735@multitable @columnfractions .15 .70
10736@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10737@code{REAL}.
10738@item @var{DIM}   @tab (Optional) Shall be a scalar of type
10739@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10740inclusive.  It may not be an optional dummy argument.
10741@item @var{MASK}  @tab Shall be of type @code{LOGICAL},
10742and conformable with @var{ARRAY}.
10743@end multitable
10744
10745@item @emph{Return value}:
10746If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10747is a scalar.  If @var{DIM} is present, the result is an array with a
10748rank one less than the rank of @var{ARRAY}, and a size corresponding to
10749the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
10750cases, the result is of the same type and kind as @var{ARRAY}.
10751
10752@item @emph{See also}:
10753@ref{MIN}, @gol
10754@ref{MINLOC}
10755@end table
10756
10757
10758
10759@node MOD
10760@section @code{MOD} --- Remainder function
10761@fnindex MOD
10762@fnindex AMOD
10763@fnindex DMOD
10764@fnindex BMOD
10765@fnindex IMOD
10766@fnindex JMOD
10767@fnindex KMOD
10768@cindex remainder
10769@cindex division, remainder
10770
10771@table @asis
10772@item @emph{Description}:
10773@code{MOD(A,P)} computes the remainder of the division of A by P@.
10774
10775@item @emph{Standard}:
10776Fortran 77 and later, has overloads that are GNU extensions
10777
10778@item @emph{Class}:
10779Elemental function
10780
10781@item @emph{Syntax}:
10782@code{RESULT = MOD(A, P)}
10783
10784@item @emph{Arguments}:
10785@multitable @columnfractions .15 .70
10786@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10787@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10788and not equal to zero.  (As a GNU extension, arguments of different kinds are
10789permitted.)
10790@end multitable
10791
10792@item @emph{Return value}:
10793The return value is the result of @code{A - (INT(A/P) * P)}. The type
10794and kind of the return value is the same as that of the arguments. The
10795returned value has the same sign as A and a magnitude less than the
10796magnitude of P.  (As a GNU extension, kind is the largest kind of the actual
10797arguments.)
10798
10799@item @emph{Example}:
10800@smallexample
10801program test_mod
10802  print *, mod(17,3)
10803  print *, mod(17.5,5.5)
10804  print *, mod(17.5d0,5.5)
10805  print *, mod(17.5,5.5d0)
10806
10807  print *, mod(-17,3)
10808  print *, mod(-17.5,5.5)
10809  print *, mod(-17.5d0,5.5)
10810  print *, mod(-17.5,5.5d0)
10811
10812  print *, mod(17,-3)
10813  print *, mod(17.5,-5.5)
10814  print *, mod(17.5d0,-5.5)
10815  print *, mod(17.5,-5.5d0)
10816end program test_mod
10817@end smallexample
10818
10819@item @emph{Specific names}:
10820@multitable @columnfractions .20 .25 .20 .31
10821@headitem Name             @tab Arguments          @tab Return type    @tab Standard
10822@item @code{MOD(A,P)}  @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later
10823@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later
10824@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later
10825@item @code{BMOD(A,P)}  @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10826@item @code{IMOD(A,P)}  @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10827@item @code{JMOD(A,P)}  @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10828@item @code{KMOD(A,P)}  @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10829@end multitable
10830
10831@item @emph{See also}:
10832@ref{MODULO}
10833
10834@end table
10835
10836
10837
10838@node MODULO
10839@section @code{MODULO} --- Modulo function
10840@fnindex MODULO
10841@cindex modulo
10842@cindex division, modulo
10843
10844@table @asis
10845@item @emph{Description}:
10846@code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10847
10848@item @emph{Standard}:
10849Fortran 95 and later
10850
10851@item @emph{Class}:
10852Elemental function
10853
10854@item @emph{Syntax}:
10855@code{RESULT = MODULO(A, P)}
10856
10857@item @emph{Arguments}:
10858@multitable @columnfractions .15 .70
10859@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10860@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10861It shall not be zero.  (As a GNU extension, arguments of different kinds are
10862permitted.)
10863@end multitable
10864
10865@item @emph{Return value}:
10866The type and kind of the result are those of the arguments.  (As a GNU
10867extension, kind is the largest kind of the actual arguments.)
10868@table @asis
10869@item If @var{A} and @var{P} are of type @code{INTEGER}:
10870@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10871@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10872(exclusive).
10873@item If @var{A} and @var{P} are of type @code{REAL}:
10874@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10875@end table
10876The returned value has the same sign as P and a magnitude less than
10877the magnitude of P.
10878
10879@item @emph{Example}:
10880@smallexample
10881program test_modulo
10882  print *, modulo(17,3)
10883  print *, modulo(17.5,5.5)
10884
10885  print *, modulo(-17,3)
10886  print *, modulo(-17.5,5.5)
10887
10888  print *, modulo(17,-3)
10889  print *, modulo(17.5,-5.5)
10890end program
10891@end smallexample
10892
10893@item @emph{See also}:
10894@ref{MOD}
10895
10896@end table
10897
10898
10899
10900@node MOVE_ALLOC
10901@section @code{MOVE_ALLOC} --- Move allocation from one object to another
10902@fnindex MOVE_ALLOC
10903@cindex moving allocation
10904@cindex allocation, moving
10905
10906@table @asis
10907@item @emph{Description}:
10908@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10909@var{TO}.  @var{FROM} will become deallocated in the process.
10910
10911@item @emph{Standard}:
10912Fortran 2003 and later
10913
10914@item @emph{Class}:
10915Pure subroutine
10916
10917@item @emph{Syntax}:
10918@code{CALL MOVE_ALLOC(FROM, TO)}
10919
10920@item @emph{Arguments}:
10921@multitable @columnfractions .15 .70
10922@item @var{FROM}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10923of any type and kind.
10924@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10925of the same type, kind and rank as @var{FROM}.
10926@end multitable
10927
10928@item @emph{Return value}:
10929None
10930
10931@item @emph{Example}:
10932@smallexample
10933program test_move_alloc
10934    integer, allocatable :: a(:), b(:)
10935
10936    allocate(a(3))
10937    a = [ 1, 2, 3 ]
10938    call move_alloc(a, b)
10939    print *, allocated(a), allocated(b)
10940    print *, b
10941end program test_move_alloc
10942@end smallexample
10943@end table
10944
10945
10946
10947@node MVBITS
10948@section @code{MVBITS} --- Move bits from one integer to another
10949@fnindex MVBITS
10950@fnindex BMVBITS
10951@fnindex IMVBITS
10952@fnindex JMVBITS
10953@fnindex KMVBITS
10954@cindex bits, move
10955
10956@table @asis
10957@item @emph{Description}:
10958Moves @var{LEN} bits from positions @var{FROMPOS} through
10959@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10960@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10961affected by the movement of bits is unchanged. The values of
10962@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10963@code{BIT_SIZE(FROM)}.
10964
10965@item @emph{Standard}:
10966Fortran 90 and later, has overloads that are GNU extensions
10967
10968@item @emph{Class}:
10969Elemental subroutine
10970
10971@item @emph{Syntax}:
10972@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10973
10974@item @emph{Arguments}:
10975@multitable @columnfractions .15 .70
10976@item @var{FROM}    @tab The type shall be @code{INTEGER}.
10977@item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10978@item @var{LEN}     @tab The type shall be @code{INTEGER}.
10979@item @var{TO}      @tab The type shall be @code{INTEGER}, of the
10980same kind as @var{FROM}.
10981@item @var{TOPOS}   @tab The type shall be @code{INTEGER}.
10982@end multitable
10983
10984@item @emph{Specific names}:
10985@multitable @columnfractions .20 .23 .20 .33
10986@headitem Name            @tab Argument            @tab Return type       @tab Standard
10987@item @code{MVBITS(A)}   @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 90 and later
10988@item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10989@item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10990@item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10991@item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10992@end multitable
10993
10994@item @emph{See also}:
10995@ref{IBCLR}, @gol
10996@ref{IBSET}, @gol
10997@ref{IBITS}, @gol
10998@ref{IAND}, @gol
10999@ref{IOR}, @gol
11000@ref{IEOR}
11001@end table
11002
11003
11004
11005@node NEAREST
11006@section @code{NEAREST} --- Nearest representable number
11007@fnindex NEAREST
11008@cindex real number, nearest different
11009@cindex floating point, nearest different
11010
11011@table @asis
11012@item @emph{Description}:
11013@code{NEAREST(X, S)} returns the processor-representable number nearest
11014to @code{X} in the direction indicated by the sign of @code{S}.
11015
11016@item @emph{Standard}:
11017Fortran 90 and later
11018
11019@item @emph{Class}:
11020Elemental function
11021
11022@item @emph{Syntax}:
11023@code{RESULT = NEAREST(X, S)}
11024
11025@item @emph{Arguments}:
11026@multitable @columnfractions .15 .70
11027@item @var{X} @tab Shall be of type @code{REAL}.
11028@item @var{S} @tab Shall be of type @code{REAL} and
11029not equal to zero.
11030@end multitable
11031
11032@item @emph{Return value}:
11033The return value is of the same type as @code{X}. If @code{S} is
11034positive, @code{NEAREST} returns the processor-representable number
11035greater than @code{X} and nearest to it. If @code{S} is negative,
11036@code{NEAREST} returns the processor-representable number smaller than
11037@code{X} and nearest to it.
11038
11039@item @emph{Example}:
11040@smallexample
11041program test_nearest
11042  real :: x, y
11043  x = nearest(42.0, 1.0)
11044  y = nearest(42.0, -1.0)
11045  write (*,"(3(G20.15))") x, y, x - y
11046end program test_nearest
11047@end smallexample
11048@end table
11049
11050
11051
11052@node NEW_LINE
11053@section @code{NEW_LINE} --- New line character
11054@fnindex NEW_LINE
11055@cindex newline
11056@cindex output, newline
11057
11058@table @asis
11059@item @emph{Description}:
11060@code{NEW_LINE(C)} returns the new-line character.
11061
11062@item @emph{Standard}:
11063Fortran 2003 and later
11064
11065@item @emph{Class}:
11066Inquiry function
11067
11068@item @emph{Syntax}:
11069@code{RESULT = NEW_LINE(C)}
11070
11071@item @emph{Arguments}:
11072@multitable @columnfractions .15 .70
11073@item @var{C}    @tab The argument shall be a scalar or array of the
11074type @code{CHARACTER}.
11075@end multitable
11076
11077@item @emph{Return value}:
11078Returns a @var{CHARACTER} scalar of length one with the new-line character of
11079the same kind as parameter @var{C}.
11080
11081@item @emph{Example}:
11082@smallexample
11083program newline
11084  implicit none
11085  write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
11086end program newline
11087@end smallexample
11088@end table
11089
11090
11091
11092@node NINT
11093@section @code{NINT} --- Nearest whole number
11094@fnindex NINT
11095@fnindex IDNINT
11096@cindex rounding, nearest whole number
11097
11098@table @asis
11099@item @emph{Description}:
11100@code{NINT(A)} rounds its argument to the nearest whole number.
11101
11102@item @emph{Standard}:
11103Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
11104
11105@item @emph{Class}:
11106Elemental function
11107
11108@item @emph{Syntax}:
11109@code{RESULT = NINT(A [, KIND])}
11110
11111@item @emph{Arguments}:
11112@multitable @columnfractions .15 .70
11113@item @var{A}    @tab The type of the argument shall be @code{REAL}.
11114@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11115expression indicating the kind parameter of the result.
11116@end multitable
11117
11118@item @emph{Return value}:
11119Returns @var{A} with the fractional portion of its magnitude eliminated by
11120rounding to the nearest whole number and with its sign preserved,
11121converted to an @code{INTEGER} of the default kind.
11122
11123@item @emph{Example}:
11124@smallexample
11125program test_nint
11126  real(4) x4
11127  real(8) x8
11128  x4 = 1.234E0_4
11129  x8 = 4.321_8
11130  print *, nint(x4), idnint(x8)
11131end program test_nint
11132@end smallexample
11133
11134@item @emph{Specific names}:
11135@multitable @columnfractions .20 .23 .20 .33
11136@headitem Name             @tab Argument           @tab Return Type     @tab Standard
11137@item @code{NINT(A)}   @tab @code{REAL(4) A}   @tab  @code{INTEGER} @tab Fortran 77 and later
11138@item @code{IDNINT(A)} @tab @code{REAL(8) A}   @tab  @code{INTEGER} @tab Fortran 77 and later
11139@end multitable
11140
11141@item @emph{See also}:
11142@ref{CEILING}, @gol
11143@ref{FLOOR}
11144@end table
11145
11146
11147
11148@node NORM2
11149@section @code{NORM2} --- Euclidean vector norms
11150@fnindex NORM2
11151@cindex Euclidean vector norm
11152@cindex L2 vector norm
11153@cindex norm, Euclidean
11154
11155@table @asis
11156@item @emph{Description}:
11157Calculates the Euclidean vector norm (@math{L_2} norm)
11158of @var{ARRAY} along dimension @var{DIM}.
11159
11160@item @emph{Standard}:
11161Fortran 2008 and later
11162
11163@item @emph{Class}:
11164Transformational function
11165
11166@item @emph{Syntax}:
11167@multitable @columnfractions .80
11168@item @code{RESULT = NORM2(ARRAY[, DIM])}
11169@end multitable
11170
11171@item @emph{Arguments}:
11172@multitable @columnfractions .15 .70
11173@item @var{ARRAY} @tab Shall be an array of type @code{REAL}
11174@item @var{DIM}   @tab (Optional) shall be a scalar of type
11175@code{INTEGER} with a value in the range from 1 to n, where n
11176equals the rank of @var{ARRAY}.
11177@end multitable
11178
11179@item @emph{Return value}:
11180The result is of the same type as @var{ARRAY}.
11181
11182If @var{DIM} is absent, a scalar with the square root of the sum of all
11183elements in @var{ARRAY} squared  is returned. Otherwise, an array of
11184rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
11185shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
11186is returned.
11187
11188@item @emph{Example}:
11189@smallexample
11190PROGRAM test_sum
11191  REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
11192  print *, NORM2(x)  ! = sqrt(55.) ~ 7.416
11193END PROGRAM
11194@end smallexample
11195@end table
11196
11197
11198
11199@node NOT
11200@section @code{NOT} --- Logical negation
11201@fnindex NOT
11202@fnindex BNOT
11203@fnindex INOT
11204@fnindex JNOT
11205@fnindex KNOT
11206@cindex bits, negate
11207@cindex bitwise logical not
11208@cindex logical not, bitwise
11209
11210@table @asis
11211@item @emph{Description}:
11212@code{NOT} returns the bitwise Boolean inverse of @var{I}.
11213
11214@item @emph{Standard}:
11215Fortran 90 and later, has overloads that are GNU extensions
11216
11217@item @emph{Class}:
11218Elemental function
11219
11220@item @emph{Syntax}:
11221@code{RESULT = NOT(I)}
11222
11223@item @emph{Arguments}:
11224@multitable @columnfractions .15 .70
11225@item @var{I} @tab The type shall be @code{INTEGER}.
11226@end multitable
11227
11228@item @emph{Return value}:
11229The return type is @code{INTEGER}, of the same kind as the
11230argument.
11231
11232@item @emph{Specific names}:
11233@multitable @columnfractions .20 .23 .20 .33
11234@headitem Name            @tab Argument            @tab Return type       @tab Standard
11235@item @code{NOT(A)}   @tab @code{INTEGER A}    @tab @code{INTEGER}    @tab Fortran 95 and later
11236@item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
11237@item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
11238@item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
11239@item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
11240@end multitable
11241
11242@item @emph{See also}:
11243@ref{IAND}, @gol
11244@ref{IEOR}, @gol
11245@ref{IOR}, @gol
11246@ref{IBITS}, @gol
11247@ref{IBSET}, @gol
11248@ref{IBCLR}
11249@end table
11250
11251
11252
11253@node NULL
11254@section @code{NULL} --- Function that returns an disassociated pointer
11255@fnindex NULL
11256@cindex pointer, status
11257@cindex pointer, disassociated
11258
11259@table @asis
11260@item @emph{Description}:
11261Returns a disassociated pointer.
11262
11263If @var{MOLD} is present, a disassociated pointer of the same type is
11264returned, otherwise the type is determined by context.
11265
11266In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
11267includes cases where it is required.
11268
11269@item @emph{Standard}:
11270Fortran 95 and later
11271
11272@item @emph{Class}:
11273Transformational function
11274
11275@item @emph{Syntax}:
11276@code{PTR => NULL([MOLD])}
11277
11278@item @emph{Arguments}:
11279@multitable @columnfractions .15 .70
11280@item @var{MOLD} @tab (Optional) shall be a pointer of any association
11281status and of any type.
11282@end multitable
11283
11284@item @emph{Return value}:
11285A disassociated pointer.
11286
11287@item @emph{Example}:
11288@smallexample
11289REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
11290@end smallexample
11291
11292@item @emph{See also}:
11293@ref{ASSOCIATED}
11294@end table
11295
11296
11297
11298@node NUM_IMAGES
11299@section @code{NUM_IMAGES} --- Function that returns the number of images
11300@fnindex NUM_IMAGES
11301@cindex coarray, @code{NUM_IMAGES}
11302@cindex images, number of
11303
11304@table @asis
11305@item @emph{Description}:
11306Returns the number of images.
11307
11308@item @emph{Standard}:
11309Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
11310Technical Specification (TS) 18508 or later
11311
11312
11313@item @emph{Class}:
11314Transformational function
11315
11316@item @emph{Syntax}:
11317@code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
11318
11319@item @emph{Arguments}:
11320@multitable @columnfractions .15 .70
11321@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
11322@item @var{FAILED}   @tab (optional, intent(in)) Scalar logical expression
11323@end multitable
11324
11325@item @emph{Return value}:
11326Scalar default-kind integer.  If @var{DISTANCE} is not present or has value 0,
11327the number of images in the current team is returned. For values smaller or
11328equal distance to the initial team, it returns the number of images index
11329on the ancestor team which has a distance of @var{DISTANCE} from the invoking
11330team. If @var{DISTANCE} is larger than the distance to the initial team, the
11331number of images of the initial team is returned. If @var{FAILED} is not present
11332the total number of images is returned; if it has the value @code{.TRUE.},
11333the number of failed images is returned, otherwise, the number of images which
11334do have not the failed status.
11335
11336@item @emph{Example}:
11337@smallexample
11338INTEGER :: value[*]
11339INTEGER :: i
11340value = THIS_IMAGE()
11341SYNC ALL
11342IF (THIS_IMAGE() == 1) THEN
11343  DO i = 1, NUM_IMAGES()
11344    WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11345  END DO
11346END IF
11347@end smallexample
11348
11349@item @emph{See also}:
11350@ref{THIS_IMAGE}, @gol
11351@ref{IMAGE_INDEX}
11352@end table
11353
11354
11355
11356@node OR
11357@section @code{OR} --- Bitwise logical OR
11358@fnindex OR
11359@cindex bitwise logical or
11360@cindex logical or, bitwise
11361
11362@table @asis
11363@item @emph{Description}:
11364Bitwise logical @code{OR}.
11365
11366This intrinsic routine is provided for backwards compatibility with
11367GNU Fortran 77.  For integer arguments, programmers should consider
11368the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11369
11370@item @emph{Standard}:
11371GNU extension
11372
11373@item @emph{Class}:
11374Function
11375
11376@item @emph{Syntax}:
11377@code{RESULT = OR(I, J)}
11378
11379@item @emph{Arguments}:
11380@multitable @columnfractions .15 .70
11381@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11382type or a scalar @code{LOGICAL} type or a boz-literal-constant.
11383@item @var{J} @tab The type shall be the same as the type of @var{I} or
11384a boz-literal-constant. @var{I} and @var{J} shall not both be
11385boz-literal-constants.  If either @var{I} and @var{J} is a
11386boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
11387@end multitable
11388
11389@item @emph{Return value}:
11390The return type is either a scalar @code{INTEGER} or a scalar
11391@code{LOGICAL}.  If the kind type parameters differ, then the
11392smaller kind type is implicitly converted to larger kind, and the
11393return has the larger kind.  A boz-literal-constant is
11394converted to an @code{INTEGER} with the kind type parameter of
11395the other argument as-if a call to @ref{INT} occurred.
11396
11397@item @emph{Example}:
11398@smallexample
11399PROGRAM test_or
11400  LOGICAL :: T = .TRUE., F = .FALSE.
11401  INTEGER :: a, b
11402  DATA a / Z'F' /, b / Z'3' /
11403
11404  WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11405  WRITE (*,*) OR(a, b)
11406END PROGRAM
11407@end smallexample
11408
11409@item @emph{See also}:
11410Fortran 95 elemental function: @gol
11411@ref{IOR}
11412@end table
11413
11414
11415
11416@node PACK
11417@section @code{PACK} --- Pack an array into an array of rank one
11418@fnindex PACK
11419@cindex array, packing
11420@cindex array, reduce dimension
11421@cindex array, gather elements
11422
11423@table @asis
11424@item @emph{Description}:
11425Stores the elements of @var{ARRAY} in an array of rank one.
11426
11427The beginning of the resulting array is made up of elements whose @var{MASK}
11428equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11429@var{VECTOR}.
11430
11431@item @emph{Standard}:
11432Fortran 90 and later
11433
11434@item @emph{Class}:
11435Transformational function
11436
11437@item @emph{Syntax}:
11438@code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11439
11440@item @emph{Arguments}:
11441@multitable @columnfractions .15 .70
11442@item @var{ARRAY}  @tab Shall be an array of any type.
11443@item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and
11444of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11445scalar.
11446@item @var{VECTOR} @tab (Optional) shall be an array of the same type
11447as @var{ARRAY} and of rank one. If present, the number of elements in
11448@var{VECTOR} shall be equal to or greater than the number of true elements
11449in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11450@var{VECTOR} shall be equal to or greater than the number of elements in
11451@var{ARRAY}.
11452@end multitable
11453
11454@item @emph{Return value}:
11455The result is an array of rank one and the same type as that of @var{ARRAY}.
11456If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11457number of @code{TRUE} values in @var{MASK} otherwise.
11458
11459@item @emph{Example}:
11460Gathering nonzero elements from an array:
11461@smallexample
11462PROGRAM test_pack_1
11463  INTEGER :: m(6)
11464  m = (/ 1, 0, 0, 0, 5, 0 /)
11465  WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
11466END PROGRAM
11467@end smallexample
11468
11469Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11470@smallexample
11471PROGRAM test_pack_2
11472  INTEGER :: m(4)
11473  m = (/ 1, 0, 0, 2 /)
11474  ! The following results in "1 2 3 4"
11475  WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))
11476END PROGRAM
11477@end smallexample
11478
11479@item @emph{See also}:
11480@ref{UNPACK}
11481@end table
11482
11483
11484
11485@node PARITY
11486@section @code{PARITY} --- Reduction with exclusive OR
11487@fnindex PARITY
11488@cindex Parity
11489@cindex Reduction, XOR
11490@cindex XOR reduction
11491
11492@table @asis
11493@item @emph{Description}:
11494Calculates the parity, i.e. the reduction using @code{.XOR.},
11495of @var{MASK} along dimension @var{DIM}.
11496
11497@item @emph{Standard}:
11498Fortran 2008 and later
11499
11500@item @emph{Class}:
11501Transformational function
11502
11503@item @emph{Syntax}:
11504@multitable @columnfractions .80
11505@item @code{RESULT = PARITY(MASK[, DIM])}
11506@end multitable
11507
11508@item @emph{Arguments}:
11509@multitable @columnfractions .15 .70
11510@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}
11511@item @var{DIM}   @tab (Optional) shall be a scalar of type
11512@code{INTEGER} with a value in the range from 1 to n, where n
11513equals the rank of @var{MASK}.
11514@end multitable
11515
11516@item @emph{Return value}:
11517The result is of the same type as @var{MASK}.
11518
11519If @var{DIM} is absent, a scalar with the parity of all elements in
11520@var{MASK} is returned, i.e. true if an odd number of elements is
11521@code{.true.} and false otherwise.  If @var{DIM} is present, an array
11522of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11523and a shape similar to that of @var{MASK} with dimension @var{DIM}
11524dropped is returned.
11525
11526@item @emph{Example}:
11527@smallexample
11528PROGRAM test_sum
11529  LOGICAL :: x(2) = [ .true., .false. ]
11530  print *, PARITY(x) ! prints "T" (true).
11531END PROGRAM
11532@end smallexample
11533@end table
11534
11535
11536
11537@node PERROR
11538@section @code{PERROR} --- Print system error message
11539@fnindex PERROR
11540@cindex system, error handling
11541
11542@table @asis
11543@item @emph{Description}:
11544Prints (on the C @code{stderr} stream) a newline-terminated error
11545message corresponding to the last system error. This is prefixed by
11546@var{STRING}, a colon and a space. See @code{perror(3)}.
11547
11548@item @emph{Standard}:
11549GNU extension
11550
11551@item @emph{Class}:
11552Subroutine
11553
11554@item @emph{Syntax}:
11555@code{CALL PERROR(STRING)}
11556
11557@item @emph{Arguments}:
11558@multitable @columnfractions .15 .70
11559@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11560default kind.
11561@end multitable
11562
11563@item @emph{See also}:
11564@ref{IERRNO}
11565@end table
11566
11567
11568
11569@node POPCNT
11570@section @code{POPCNT} --- Number of bits set
11571@fnindex POPCNT
11572@cindex binary representation
11573@cindex bits set
11574
11575@table @asis
11576@item @emph{Description}:
11577@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11578representation of @code{I}.
11579
11580@item @emph{Standard}:
11581Fortran 2008 and later
11582
11583@item @emph{Class}:
11584Elemental function
11585
11586@item @emph{Syntax}:
11587@code{RESULT = POPCNT(I)}
11588
11589@item @emph{Arguments}:
11590@multitable @columnfractions .15 .70
11591@item @var{I} @tab Shall be of type @code{INTEGER}.
11592@end multitable
11593
11594@item @emph{Return value}:
11595The return value is of type @code{INTEGER} and of the default integer
11596kind.
11597
11598@item @emph{Example}:
11599@smallexample
11600program test_population
11601  print *, popcnt(127),       poppar(127)
11602  print *, popcnt(huge(0_4)), poppar(huge(0_4))
11603  print *, popcnt(huge(0_8)), poppar(huge(0_8))
11604end program test_population
11605@end smallexample
11606@item @emph{See also}:
11607@ref{POPPAR}, @gol
11608@ref{LEADZ}, @gol
11609@ref{TRAILZ}
11610@end table
11611
11612
11613
11614@node POPPAR
11615@section @code{POPPAR} --- Parity of the number of bits set
11616@fnindex POPPAR
11617@cindex binary representation
11618@cindex parity
11619
11620@table @asis
11621@item @emph{Description}:
11622@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11623of the number of bits set ('1' bits) in the binary representation of
11624@code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11625and 1 for an odd number of '1' bits.
11626
11627@item @emph{Standard}:
11628Fortran 2008 and later
11629
11630@item @emph{Class}:
11631Elemental function
11632
11633@item @emph{Syntax}:
11634@code{RESULT = POPPAR(I)}
11635
11636@item @emph{Arguments}:
11637@multitable @columnfractions .15 .70
11638@item @var{I} @tab Shall be of type @code{INTEGER}.
11639@end multitable
11640
11641@item @emph{Return value}:
11642The return value is of type @code{INTEGER} and of the default integer
11643kind.
11644
11645@item @emph{Example}:
11646@smallexample
11647program test_population
11648  print *, popcnt(127),       poppar(127)
11649  print *, popcnt(huge(0_4)), poppar(huge(0_4))
11650  print *, popcnt(huge(0_8)), poppar(huge(0_8))
11651end program test_population
11652@end smallexample
11653@item @emph{See also}:
11654@ref{POPCNT}, @gol
11655@ref{LEADZ}, @gol
11656@ref{TRAILZ}
11657@end table
11658
11659
11660
11661@node PRECISION
11662@section @code{PRECISION} --- Decimal precision of a real kind
11663@fnindex PRECISION
11664@cindex model representation, precision
11665
11666@table @asis
11667@item @emph{Description}:
11668@code{PRECISION(X)} returns the decimal precision in the model of the
11669type of @code{X}.
11670
11671@item @emph{Standard}:
11672Fortran 90 and later
11673
11674@item @emph{Class}:
11675Inquiry function
11676
11677@item @emph{Syntax}:
11678@code{RESULT = PRECISION(X)}
11679
11680@item @emph{Arguments}:
11681@multitable @columnfractions .15 .70
11682@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. It may
11683be scalar or valued.
11684@end multitable
11685
11686@item @emph{Return value}:
11687The return value is of type @code{INTEGER} and of the default integer
11688kind.
11689
11690@item @emph{Example}:
11691@smallexample
11692program prec_and_range
11693  real(kind=4) :: x(2)
11694  complex(kind=8) :: y
11695
11696  print *, precision(x), range(x)
11697  print *, precision(y), range(y)
11698end program prec_and_range
11699@end smallexample
11700@item @emph{See also}:
11701@ref{SELECTED_REAL_KIND}, @gol
11702@ref{RANGE}
11703@end table
11704
11705
11706
11707@node PRESENT
11708@section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11709@fnindex PRESENT
11710
11711@table @asis
11712@item @emph{Description}:
11713Determines whether an optional dummy argument is present.
11714
11715@item @emph{Standard}:
11716Fortran 90 and later
11717
11718@item @emph{Class}:
11719Inquiry function
11720
11721@item @emph{Syntax}:
11722@code{RESULT = PRESENT(A)}
11723
11724@item @emph{Arguments}:
11725@multitable @columnfractions .15 .70
11726@item @var{A} @tab May be of any type and may be a pointer, scalar or array
11727value, or a dummy procedure. It shall be the name of an optional dummy argument
11728accessible within the current subroutine or function.
11729@end multitable
11730
11731@item @emph{Return value}:
11732Returns either @code{TRUE} if the optional argument @var{A} is present, or
11733@code{FALSE} otherwise.
11734
11735@item @emph{Example}:
11736@smallexample
11737PROGRAM test_present
11738  WRITE(*,*) f(), f(42)      ! "F T"
11739CONTAINS
11740  LOGICAL FUNCTION f(x)
11741    INTEGER, INTENT(IN), OPTIONAL :: x
11742    f = PRESENT(x)
11743  END FUNCTION
11744END PROGRAM
11745@end smallexample
11746@end table
11747
11748
11749
11750@node PRODUCT
11751@section @code{PRODUCT} --- Product of array elements
11752@fnindex PRODUCT
11753@cindex array, product
11754@cindex array, multiply elements
11755@cindex array, conditionally multiply elements
11756@cindex multiply array elements
11757
11758@table @asis
11759@item @emph{Description}:
11760Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11761the corresponding element in @var{MASK} is @code{TRUE}.
11762
11763@item @emph{Standard}:
11764Fortran 90 and later
11765
11766@item @emph{Class}:
11767Transformational function
11768
11769@item @emph{Syntax}:
11770@multitable @columnfractions .80
11771@item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11772@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11773@end multitable
11774
11775@item @emph{Arguments}:
11776@multitable @columnfractions .15 .70
11777@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11778@code{REAL} or @code{COMPLEX}.
11779@item @var{DIM}   @tab (Optional) shall be a scalar of type
11780@code{INTEGER} with a value in the range from 1 to n, where n
11781equals the rank of @var{ARRAY}.
11782@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
11783and either be a scalar or an array of the same shape as @var{ARRAY}.
11784@end multitable
11785
11786@item @emph{Return value}:
11787The result is of the same type as @var{ARRAY}.
11788
11789If @var{DIM} is absent, a scalar with the product of all elements in
11790@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11791the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11792dimension @var{DIM} dropped is returned.
11793
11794
11795@item @emph{Example}:
11796@smallexample
11797PROGRAM test_product
11798  INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11799  print *, PRODUCT(x)                    ! all elements, product = 120
11800  print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11801END PROGRAM
11802@end smallexample
11803
11804@item @emph{See also}:
11805@ref{SUM}
11806@end table
11807
11808
11809
11810@node RADIX
11811@section @code{RADIX} --- Base of a model number
11812@fnindex RADIX
11813@cindex model representation, base
11814@cindex model representation, radix
11815
11816@table @asis
11817@item @emph{Description}:
11818@code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11819
11820@item @emph{Standard}:
11821Fortran 90 and later
11822
11823@item @emph{Class}:
11824Inquiry function
11825
11826@item @emph{Syntax}:
11827@code{RESULT = RADIX(X)}
11828
11829@item @emph{Arguments}:
11830@multitable @columnfractions .15 .70
11831@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11832@end multitable
11833
11834@item @emph{Return value}:
11835The return value is a scalar of type @code{INTEGER} and of the default
11836integer kind.
11837
11838@item @emph{Example}:
11839@smallexample
11840program test_radix
11841  print *, "The radix for the default integer kind is", radix(0)
11842  print *, "The radix for the default real kind is", radix(0.0)
11843end program test_radix
11844@end smallexample
11845@item @emph{See also}:
11846@ref{SELECTED_REAL_KIND}
11847@end table
11848
11849
11850
11851@node RAN
11852@section @code{RAN} --- Real pseudo-random number
11853@fnindex RAN
11854@cindex random number generation
11855
11856@table @asis
11857@item @emph{Description}:
11858For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11859provided as an alias for @code{RAND}.  See @ref{RAND} for complete
11860documentation.
11861
11862@item @emph{Standard}:
11863GNU extension
11864
11865@item @emph{Class}:
11866Function
11867
11868@item @emph{See also}:
11869@ref{RAND}, @gol
11870@ref{RANDOM_NUMBER}
11871@end table
11872
11873
11874
11875@node RAND
11876@section @code{RAND} --- Real pseudo-random number
11877@fnindex RAND
11878@cindex random number generation
11879
11880@table @asis
11881@item @emph{Description}:
11882@code{RAND(FLAG)} returns a pseudo-random number from a uniform
11883distribution between 0 and 1. If @var{FLAG} is 0, the next number
11884in the current sequence is returned; if @var{FLAG} is 1, the generator
11885is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11886it is used as a new seed with @code{SRAND}.
11887
11888This intrinsic routine is provided for backwards compatibility with
11889GNU Fortran 77. It implements a simple modulo generator as provided
11890by @command{g77}. For new code, one should consider the use of
11891@ref{RANDOM_NUMBER} as it implements a superior algorithm.
11892
11893@item @emph{Standard}:
11894GNU extension
11895
11896@item @emph{Class}:
11897Function
11898
11899@item @emph{Syntax}:
11900@code{RESULT = RAND(I)}
11901
11902@item @emph{Arguments}:
11903@multitable @columnfractions .15 .70
11904@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11905@end multitable
11906
11907@item @emph{Return value}:
11908The return value is of @code{REAL} type and the default kind.
11909
11910@item @emph{Example}:
11911@smallexample
11912program test_rand
11913  integer,parameter :: seed = 86456
11914
11915  call srand(seed)
11916  print *, rand(), rand(), rand(), rand()
11917  print *, rand(seed), rand(), rand(), rand()
11918end program test_rand
11919@end smallexample
11920
11921@item @emph{See also}:
11922@ref{SRAND}, @gol
11923@ref{RANDOM_NUMBER}
11924
11925@end table
11926
11927
11928@node RANDOM_INIT
11929@section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator
11930@fnindex RANDOM_INIT
11931@cindex random number generation, initialization
11932
11933@table @asis
11934@item @emph{Description}:
11935Initializes the state of the pseudorandom number generator used by
11936@code{RANDOM_NUMBER}.
11937
11938@item @emph{Standard}:
11939Fortran 2018
11940
11941@item @emph{Class}:
11942Subroutine
11943
11944@item @emph{Syntax}:
11945@code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)}
11946
11947@item @emph{Arguments}:
11948@multitable @columnfractions .25 .70
11949@item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type,
11950and it is @code{INTENT(IN)}.  If it is @code{.true.}, the seed is set to
11951a processor-dependent value that is the same each time @code{RANDOM_INIT}
11952is called from the same image.  The term ``same image'' means a single
11953instance of program execution.  The sequence of random numbers is different
11954for repeated execution of the program.  If it is @code{.false.}, the seed
11955is set to a processor-dependent value.
11956@item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a
11957@code{LOGICAL} type, and it is @code{INTENT(IN)}.  If it is @code{.true.},
11958the seed is set to a processor-dependent value that is distinct from th
11959seed set by a call to @code{RANDOM_INIT} in another image.  If it is
11960@code{.false.}, the seed is set to a value that does depend which image called
11961@code{RANDOM_INIT}.
11962@end multitable
11963
11964@item @emph{Example}:
11965@smallexample
11966program test_random_seed
11967  implicit none
11968  real x(3), y(3)
11969  call random_init(.true., .true.)
11970  call random_number(x)
11971  call random_init(.true., .true.)
11972  call random_number(y)
11973  ! x and y are the same sequence
11974  if (any(x /= y)) call abort
11975end program test_random_seed
11976@end smallexample
11977
11978@item @emph{See also}:
11979@ref{RANDOM_NUMBER}, @gol
11980@ref{RANDOM_SEED}
11981@end table
11982
11983
11984@node RANDOM_NUMBER
11985@section @code{RANDOM_NUMBER} --- Pseudo-random number
11986@fnindex RANDOM_NUMBER
11987@cindex random number generation
11988
11989@table @asis
11990@item @emph{Description}:
11991Returns a single pseudorandom number or an array of pseudorandom numbers
11992from the uniform distribution over the range @math{ 0 \leq x < 1}.
11993
11994The runtime-library implements the xoshiro256** pseudorandom number
11995generator (PRNG). This generator has a period of @math{2^{256} - 1},
11996and when using multiple threads up to @math{2^{128}} threads can each
11997generate @math{2^{128}} random numbers before any aliasing occurs.
11998
11999Note that in a multi-threaded program (e.g. using OpenMP directives),
12000each thread will have its own random number state. For details of the
12001seeding procedure, see the documentation for the @code{RANDOM_SEED}
12002intrinsic.
12003
12004
12005@item @emph{Standard}:
12006Fortran 90 and later
12007
12008@item @emph{Class}:
12009Subroutine
12010
12011@item @emph{Syntax}:
12012@code{CALL RANDOM_NUMBER(HARVEST)}
12013
12014@item @emph{Arguments}:
12015@multitable @columnfractions .15 .70
12016@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
12017@end multitable
12018
12019@item @emph{Example}:
12020@smallexample
12021program test_random_number
12022  REAL :: r(5,5)
12023  CALL RANDOM_NUMBER(r)
12024end program
12025@end smallexample
12026
12027@item @emph{See also}:
12028@ref{RANDOM_SEED}, @gol
12029@ref{RANDOM_INIT}
12030@end table
12031
12032
12033
12034@node RANDOM_SEED
12035@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
12036@fnindex RANDOM_SEED
12037@cindex random number generation, seeding
12038@cindex seeding a random number generator
12039
12040@table @asis
12041@item @emph{Description}:
12042Restarts or queries the state of the pseudorandom number generator used by
12043@code{RANDOM_NUMBER}.
12044
12045If @code{RANDOM_SEED} is called without arguments, it is seeded with
12046random data retrieved from the operating system.
12047
12048As an extension to the Fortran standard, the GFortran
12049@code{RANDOM_NUMBER} supports multiple threads. Each thread in a
12050multi-threaded program has its own seed.  When @code{RANDOM_SEED} is
12051called either without arguments or with the @var{PUT} argument, the
12052given seed is copied into a master seed as well as the seed of the
12053current thread. When a new thread uses @code{RANDOM_NUMBER} for the
12054first time, the seed is copied from the master seed, and forwarded
12055@math{N * 2^{128}} steps to guarantee that the random stream does not
12056alias any other stream in the system, where @var{N} is the number of
12057threads that have used @code{RANDOM_NUMBER} so far during the program
12058execution.
12059
12060@item @emph{Standard}:
12061Fortran 90 and later
12062
12063@item @emph{Class}:
12064Subroutine
12065
12066@item @emph{Syntax}:
12067@code{CALL RANDOM_SEED([SIZE, PUT, GET])}
12068
12069@item @emph{Arguments}:
12070@multitable @columnfractions .15 .70
12071@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
12072@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
12073of the arrays used with the @var{PUT} and @var{GET} arguments.
12074@item @var{PUT}  @tab (Optional) Shall be an array of type default
12075@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
12076the array must be larger than or equal to the number returned by the
12077@var{SIZE} argument.
12078@item @var{GET}  @tab (Optional) Shall be an array of type default
12079@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
12080of the array must be larger than or equal to the number returned by
12081the @var{SIZE} argument.
12082@end multitable
12083
12084@item @emph{Example}:
12085@smallexample
12086program test_random_seed
12087  implicit none
12088  integer, allocatable :: seed(:)
12089  integer :: n
12090
12091  call random_seed(size = n)
12092  allocate(seed(n))
12093  call random_seed(get=seed)
12094  write (*, *) seed
12095end program test_random_seed
12096@end smallexample
12097
12098@item @emph{See also}:
12099@ref{RANDOM_NUMBER}, @gol
12100@ref{RANDOM_INIT}
12101@end table
12102
12103
12104
12105@node RANGE
12106@section @code{RANGE} --- Decimal exponent range
12107@fnindex RANGE
12108@cindex model representation, range
12109
12110@table @asis
12111@item @emph{Description}:
12112@code{RANGE(X)} returns the decimal exponent range in the model of the
12113type of @code{X}.
12114
12115@item @emph{Standard}:
12116Fortran 90 and later
12117
12118@item @emph{Class}:
12119Inquiry function
12120
12121@item @emph{Syntax}:
12122@code{RESULT = RANGE(X)}
12123
12124@item @emph{Arguments}:
12125@multitable @columnfractions .15 .70
12126@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
12127or @code{COMPLEX}.
12128@end multitable
12129
12130@item @emph{Return value}:
12131The return value is of type @code{INTEGER} and of the default integer
12132kind.
12133
12134@item @emph{Example}:
12135See @code{PRECISION} for an example.
12136@item @emph{See also}:
12137@ref{SELECTED_REAL_KIND}, @gol
12138@ref{PRECISION}
12139@end table
12140
12141
12142
12143@node RANK
12144@section @code{RANK} --- Rank of a data object
12145@fnindex RANK
12146@cindex rank
12147
12148@table @asis
12149@item @emph{Description}:
12150@code{RANK(A)} returns the rank of a scalar or array data object.
12151
12152@item @emph{Standard}:
12153Technical Specification (TS) 29113
12154
12155@item @emph{Class}:
12156Inquiry function
12157
12158@item @emph{Syntax}:
12159@code{RESULT = RANK(A)}
12160
12161@item @emph{Arguments}:
12162@multitable @columnfractions .15 .70
12163@item @var{A} @tab can be of any type
12164@end multitable
12165
12166@item @emph{Return value}:
12167The return value is of type @code{INTEGER} and of the default integer
12168kind. For arrays, their rank is returned; for scalars zero is returned.
12169
12170@item @emph{Example}:
12171@smallexample
12172program test_rank
12173  integer :: a
12174  real, allocatable :: b(:,:)
12175
12176  print *, rank(a), rank(b) ! Prints:  0  2
12177end program test_rank
12178@end smallexample
12179
12180@end table
12181
12182
12183
12184@node REAL
12185@section @code{REAL} --- Convert to real type
12186@fnindex REAL
12187@fnindex REALPART
12188@fnindex FLOAT
12189@fnindex DFLOAT
12190@fnindex FLOATI
12191@fnindex FLOATJ
12192@fnindex FLOATK
12193@fnindex SNGL
12194@cindex conversion, to real
12195@cindex complex numbers, real part
12196
12197@table @asis
12198@item @emph{Description}:
12199@code{REAL(A [, KIND])} converts its argument @var{A} to a real type.  The
12200@code{REALPART} function is provided for compatibility with @command{g77},
12201and its use is strongly discouraged.
12202
12203@item @emph{Standard}:
12204Fortran 77 and later, with @var{KIND} argument Fortran 90 and later, has GNU extensions
12205
12206@item @emph{Class}:
12207Elemental function
12208
12209@item @emph{Syntax}:
12210@multitable @columnfractions .80
12211@item @code{RESULT = REAL(A [, KIND])}
12212@item @code{RESULT = REALPART(Z)}
12213@end multitable
12214
12215@item @emph{Arguments}:
12216@multitable @columnfractions .15 .70
12217@item @var{A}    @tab Shall be @code{INTEGER}, @code{REAL}, or
12218@code{COMPLEX}.
12219@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12220expression indicating the kind parameter of the result.
12221@end multitable
12222
12223@item @emph{Return value}:
12224These functions return a @code{REAL} variable or array under
12225the following rules:
12226
12227@table @asis
12228@item (A)
12229@code{REAL(A)} is converted to a default real type if @var{A} is an
12230integer or real variable.
12231@item (B)
12232@code{REAL(A)} is converted to a real type with the kind type parameter
12233of @var{A} if @var{A} is a complex variable.
12234@item (C)
12235@code{REAL(A, KIND)} is converted to a real type with kind type
12236parameter @var{KIND} if @var{A} is a complex, integer, or real
12237variable.
12238@end table
12239
12240@item @emph{Example}:
12241@smallexample
12242program test_real
12243  complex :: x = (1.0, 2.0)
12244  print *, real(x), real(x,8), realpart(x)
12245end program test_real
12246@end smallexample
12247
12248@item @emph{Specific names}:
12249@multitable @columnfractions .20 .23 .20 .33
12250@headitem Name             @tab Argument           @tab Return type     @tab Standard
12251@item @code{FLOAT(A)}  @tab @code{INTEGER(4)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
12252@item @code{DFLOAT(A)} @tab @code{INTEGER(4)}  @tab @code{REAL(8)}  @tab GNU extension
12253@item @code{FLOATI(A)} @tab @code{INTEGER(2)}  @tab @code{REAL(4)}  @tab GNU extension (-fdec)
12254@item @code{FLOATJ(A)} @tab @code{INTEGER(4)}  @tab @code{REAL(4)}  @tab GNU extension (-fdec)
12255@item @code{FLOATK(A)} @tab @code{INTEGER(8)}  @tab @code{REAL(4)}  @tab GNU extension (-fdec)
12256@item @code{SNGL(A)}   @tab @code{REAL(8)}     @tab @code{REAL(4)}  @tab Fortran 77 and later
12257@end multitable
12258
12259
12260@item @emph{See also}:
12261@ref{DBLE}
12262
12263@end table
12264
12265
12266
12267@node RENAME
12268@section @code{RENAME} --- Rename a file
12269@fnindex RENAME
12270@cindex file system, rename file
12271
12272@table @asis
12273@item @emph{Description}:
12274Renames a file from file @var{PATH1} to @var{PATH2}. A null
12275character (@code{CHAR(0)}) can be used to mark the end of the names in
12276@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12277names are ignored.  If the @var{STATUS} argument is supplied, it
12278contains 0 on success or a nonzero error code upon return; see
12279@code{rename(2)}.
12280
12281This intrinsic is provided in both subroutine and function forms;
12282however, only one form can be used in any given program unit.
12283
12284@item @emph{Standard}:
12285GNU extension
12286
12287@item @emph{Class}:
12288Subroutine, function
12289
12290@item @emph{Syntax}:
12291@multitable @columnfractions .80
12292@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
12293@item @code{STATUS = RENAME(PATH1, PATH2)}
12294@end multitable
12295
12296@item @emph{Arguments}:
12297@multitable @columnfractions .15 .70
12298@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12299@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12300@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12301@end multitable
12302
12303@item @emph{See also}:
12304@ref{LINK}
12305
12306@end table
12307
12308
12309
12310@node REPEAT
12311@section @code{REPEAT} --- Repeated string concatenation
12312@fnindex REPEAT
12313@cindex string, repeat
12314@cindex string, concatenate
12315
12316@table @asis
12317@item @emph{Description}:
12318Concatenates @var{NCOPIES} copies of a string.
12319
12320@item @emph{Standard}:
12321Fortran 90 and later
12322
12323@item @emph{Class}:
12324Transformational function
12325
12326@item @emph{Syntax}:
12327@code{RESULT = REPEAT(STRING, NCOPIES)}
12328
12329@item @emph{Arguments}:
12330@multitable @columnfractions .15 .70
12331@item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER}.
12332@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
12333@end multitable
12334
12335@item @emph{Return value}:
12336A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
12337of @var{STRING}.
12338
12339@item @emph{Example}:
12340@smallexample
12341program test_repeat
12342  write(*,*) repeat("x", 5)   ! "xxxxx"
12343end program
12344@end smallexample
12345@end table
12346
12347
12348
12349@node RESHAPE
12350@section @code{RESHAPE} --- Function to reshape an array
12351@fnindex RESHAPE
12352@cindex array, change dimensions
12353@cindex array, transmogrify
12354
12355@table @asis
12356@item @emph{Description}:
12357Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
12358the new array may be padded with elements from @var{PAD} or permuted
12359as defined by @var{ORDER}.
12360
12361@item @emph{Standard}:
12362Fortran 90 and later
12363
12364@item @emph{Class}:
12365Transformational function
12366
12367@item @emph{Syntax}:
12368@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
12369
12370@item @emph{Arguments}:
12371@multitable @columnfractions .15 .70
12372@item @var{SOURCE} @tab Shall be an array of any type.
12373@item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an
12374array of rank one. Its values must be positive or zero.
12375@item @var{PAD}    @tab (Optional) shall be an array of the same
12376type as @var{SOURCE}.
12377@item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
12378and an array of the same shape as @var{SHAPE}. Its values shall
12379be a permutation of the numbers from 1 to n, where n is the size of
12380@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
12381be assumed.
12382@end multitable
12383
12384@item @emph{Return value}:
12385The result is an array of shape @var{SHAPE} with the same type as
12386@var{SOURCE}.
12387
12388@item @emph{Example}:
12389@smallexample
12390PROGRAM test_reshape
12391  INTEGER, DIMENSION(4) :: x
12392  WRITE(*,*) SHAPE(x)                       ! prints "4"
12393  WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
12394END PROGRAM
12395@end smallexample
12396
12397@item @emph{See also}:
12398@ref{SHAPE}
12399@end table
12400
12401
12402
12403@node RRSPACING
12404@section @code{RRSPACING} --- Reciprocal of the relative spacing
12405@fnindex RRSPACING
12406@cindex real number, relative spacing
12407@cindex floating point, relative spacing
12408
12409
12410@table @asis
12411@item @emph{Description}:
12412@code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
12413model numbers near @var{X}.
12414
12415@item @emph{Standard}:
12416Fortran 90 and later
12417
12418@item @emph{Class}:
12419Elemental function
12420
12421@item @emph{Syntax}:
12422@code{RESULT = RRSPACING(X)}
12423
12424@item @emph{Arguments}:
12425@multitable @columnfractions .15 .70
12426@item @var{X} @tab Shall be of type @code{REAL}.
12427@end multitable
12428
12429@item @emph{Return value}:
12430The return value is of the same type and kind as @var{X}.
12431The value returned is equal to
12432@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12433
12434@item @emph{See also}:
12435@ref{SPACING}
12436@end table
12437
12438
12439
12440@node RSHIFT
12441@section @code{RSHIFT} --- Right shift bits
12442@fnindex RSHIFT
12443@cindex bits, shift right
12444
12445@table @asis
12446@item @emph{Description}:
12447@code{RSHIFT} returns a value corresponding to @var{I} with all of the
12448bits shifted right by @var{SHIFT} places.  @var{SHIFT} shall be
12449nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
12450the result value is undefined.  Bits shifted out from the right end
12451are lost. The fill is arithmetic: the bits shifted in from the left
12452end are equal to the leftmost bit, which in two's complement
12453representation is the sign bit.
12454
12455This function has been superseded by the @code{SHIFTA} intrinsic, which
12456is standard in Fortran 2008 and later.
12457
12458@item @emph{Standard}:
12459GNU extension
12460
12461@item @emph{Class}:
12462Elemental function
12463
12464@item @emph{Syntax}:
12465@code{RESULT = RSHIFT(I, SHIFT)}
12466
12467@item @emph{Arguments}:
12468@multitable @columnfractions .15 .70
12469@item @var{I} @tab The type shall be @code{INTEGER}.
12470@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12471@end multitable
12472
12473@item @emph{Return value}:
12474The return value is of type @code{INTEGER} and of the same kind as
12475@var{I}.
12476
12477@item @emph{See also}:
12478@ref{ISHFT}, @gol
12479@ref{ISHFTC}, @gol
12480@ref{LSHIFT}, @gol
12481@ref{SHIFTA}, @gol
12482@ref{SHIFTR}, @gol
12483@ref{SHIFTL}
12484
12485@end table
12486
12487
12488
12489@node SAME_TYPE_AS
12490@section @code{SAME_TYPE_AS} ---  Query dynamic types for equality
12491@fnindex SAME_TYPE_AS
12492
12493@table @asis
12494@item @emph{Description}:
12495Query dynamic types for equality.
12496
12497@item @emph{Standard}:
12498Fortran 2003 and later
12499
12500@item @emph{Class}:
12501Inquiry function
12502
12503@item @emph{Syntax}:
12504@code{RESULT = SAME_TYPE_AS(A, B)}
12505
12506@item @emph{Arguments}:
12507@multitable @columnfractions .15 .70
12508@item @var{A} @tab Shall be an object of extensible declared type or
12509unlimited polymorphic.
12510@item @var{B} @tab Shall be an object of extensible declared type or
12511unlimited polymorphic.
12512@end multitable
12513
12514@item @emph{Return value}:
12515The return value is a scalar of type default logical. It is true if and
12516only if the dynamic type of A is the same as the dynamic type of B.
12517
12518@item @emph{See also}:
12519@ref{EXTENDS_TYPE_OF}
12520
12521@end table
12522
12523
12524
12525@node SCALE
12526@section @code{SCALE} --- Scale a real value
12527@fnindex SCALE
12528@cindex real number, scale
12529@cindex floating point, scale
12530
12531@table @asis
12532@item @emph{Description}:
12533@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12534
12535@item @emph{Standard}:
12536Fortran 90 and later
12537
12538@item @emph{Class}:
12539Elemental function
12540
12541@item @emph{Syntax}:
12542@code{RESULT = SCALE(X, I)}
12543
12544@item @emph{Arguments}:
12545@multitable @columnfractions .15 .70
12546@item @var{X} @tab The type of the argument shall be a @code{REAL}.
12547@item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12548@end multitable
12549
12550@item @emph{Return value}:
12551The return value is of the same type and kind as @var{X}.
12552Its value is @code{X * RADIX(X)**I}.
12553
12554@item @emph{Example}:
12555@smallexample
12556program test_scale
12557  real :: x = 178.1387e-4
12558  integer :: i = 5
12559  print *, scale(x,i), x*radix(x)**i
12560end program test_scale
12561@end smallexample
12562
12563@end table
12564
12565
12566
12567@node SCAN
12568@section @code{SCAN} --- Scan a string for the presence of a set of characters
12569@fnindex SCAN
12570@cindex string, find subset
12571
12572@table @asis
12573@item @emph{Description}:
12574Scans a @var{STRING} for any of the characters in a @var{SET}
12575of characters.
12576
12577If @var{BACK} is either absent or equals @code{FALSE}, this function
12578returns the position of the leftmost character of @var{STRING} that is
12579in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12580is returned. If no character of @var{SET} is found in @var{STRING}, the
12581result is zero.
12582
12583@item @emph{Standard}:
12584Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12585
12586@item @emph{Class}:
12587Elemental function
12588
12589@item @emph{Syntax}:
12590@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12591
12592@item @emph{Arguments}:
12593@multitable @columnfractions .15 .70
12594@item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12595@item @var{SET}    @tab Shall be of type @code{CHARACTER}.
12596@item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
12597@item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
12598expression indicating the kind parameter of the result.
12599@end multitable
12600
12601@item @emph{Return value}:
12602The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12603@var{KIND} is absent, the return value is of default integer kind.
12604
12605@item @emph{Example}:
12606@smallexample
12607PROGRAM test_scan
12608  WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
12609  WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
12610  WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
12611END PROGRAM
12612@end smallexample
12613
12614@item @emph{See also}:
12615@ref{INDEX intrinsic}, @gol
12616@ref{VERIFY}
12617@end table
12618
12619
12620
12621@node SECNDS
12622@section @code{SECNDS} --- Time function
12623@fnindex SECNDS
12624@cindex time, elapsed
12625@cindex elapsed time
12626
12627@table @asis
12628@item @emph{Description}:
12629@code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12630@var{X} is a reference time, also in seconds. If this is zero, the time in
12631seconds from midnight is returned. This function is non-standard and its
12632use is discouraged.
12633
12634@item @emph{Standard}:
12635GNU extension
12636
12637@item @emph{Class}:
12638Function
12639
12640@item @emph{Syntax}:
12641@code{RESULT = SECNDS (X)}
12642
12643@item @emph{Arguments}:
12644@multitable @columnfractions .15 .70
12645@item @var{T}     @tab Shall be of type @code{REAL(4)}.
12646@item @var{X}     @tab Shall be of type @code{REAL(4)}.
12647@end multitable
12648
12649@item @emph{Return value}:
12650None
12651
12652@item @emph{Example}:
12653@smallexample
12654program test_secnds
12655    integer :: i
12656    real(4) :: t1, t2
12657    print *, secnds (0.0)   ! seconds since midnight
12658    t1 = secnds (0.0)       ! reference time
12659    do i = 1, 10000000      ! do something
12660    end do
12661    t2 = secnds (t1)        ! elapsed time
12662    print *, "Something took ", t2, " seconds."
12663end program test_secnds
12664@end smallexample
12665@end table
12666
12667
12668
12669@node SECOND
12670@section @code{SECOND} --- CPU time function
12671@fnindex SECOND
12672@cindex time, elapsed
12673@cindex elapsed time
12674
12675@table @asis
12676@item @emph{Description}:
12677Returns a @code{REAL(4)} value representing the elapsed CPU time in
12678seconds.  This provides the same functionality as the standard
12679@code{CPU_TIME} intrinsic, and is only included for backwards
12680compatibility.
12681
12682This intrinsic is provided in both subroutine and function forms;
12683however, only one form can be used in any given program unit.
12684
12685@item @emph{Standard}:
12686GNU extension
12687
12688@item @emph{Class}:
12689Subroutine, function
12690
12691@item @emph{Syntax}:
12692@multitable @columnfractions .80
12693@item @code{CALL SECOND(TIME)}
12694@item @code{TIME = SECOND()}
12695@end multitable
12696
12697@item @emph{Arguments}:
12698@multitable @columnfractions .15 .70
12699@item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
12700@end multitable
12701
12702@item @emph{Return value}:
12703In either syntax, @var{TIME} is set to the process's current runtime in
12704seconds.
12705
12706@item @emph{See also}:
12707@ref{CPU_TIME}
12708
12709@end table
12710
12711
12712
12713@node SELECTED_CHAR_KIND
12714@section @code{SELECTED_CHAR_KIND} --- Choose character kind
12715@fnindex SELECTED_CHAR_KIND
12716@cindex character kind
12717@cindex kind, character
12718
12719@table @asis
12720@item @emph{Description}:
12721
12722@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12723set named @var{NAME}, if a character set with such a name is supported,
12724or @math{-1} otherwise. Currently, supported character sets include
12725``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12726(Universal Character Set, UCS-4) which is commonly known as Unicode.
12727
12728@item @emph{Standard}:
12729Fortran 2003 and later
12730
12731@item @emph{Class}:
12732Transformational function
12733
12734@item @emph{Syntax}:
12735@code{RESULT = SELECTED_CHAR_KIND(NAME)}
12736
12737@item @emph{Arguments}:
12738@multitable @columnfractions .15 .70
12739@item @var{NAME} @tab Shall be a scalar and of the default character type.
12740@end multitable
12741
12742@item @emph{Example}:
12743@smallexample
12744program character_kind
12745  use iso_fortran_env
12746  implicit none
12747  integer, parameter :: ascii = selected_char_kind ("ascii")
12748  integer, parameter :: ucs4  = selected_char_kind ('ISO_10646')
12749
12750  character(kind=ascii, len=26) :: alphabet
12751  character(kind=ucs4,  len=30) :: hello_world
12752
12753  alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12754  hello_world = ucs4_'Hello World and Ni Hao -- ' &
12755                // char (int (z'4F60'), ucs4)     &
12756                // char (int (z'597D'), ucs4)
12757
12758  write (*,*) alphabet
12759
12760  open (output_unit, encoding='UTF-8')
12761  write (*,*) trim (hello_world)
12762end program character_kind
12763@end smallexample
12764@end table
12765
12766
12767
12768@node SELECTED_INT_KIND
12769@section @code{SELECTED_INT_KIND} --- Choose integer kind
12770@fnindex SELECTED_INT_KIND
12771@cindex integer kind
12772@cindex kind, integer
12773
12774@table @asis
12775@item @emph{Description}:
12776@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12777type that can represent all values ranging from @math{-10^R} (exclusive)
12778to @math{10^R} (exclusive). If there is no integer kind that accommodates
12779this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12780
12781@item @emph{Standard}:
12782Fortran 90 and later
12783
12784@item @emph{Class}:
12785Transformational function
12786
12787@item @emph{Syntax}:
12788@code{RESULT = SELECTED_INT_KIND(R)}
12789
12790@item @emph{Arguments}:
12791@multitable @columnfractions .15 .70
12792@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12793@end multitable
12794
12795@item @emph{Example}:
12796@smallexample
12797program large_integers
12798  integer,parameter :: k5 = selected_int_kind(5)
12799  integer,parameter :: k15 = selected_int_kind(15)
12800  integer(kind=k5) :: i5
12801  integer(kind=k15) :: i15
12802
12803  print *, huge(i5), huge(i15)
12804
12805  ! The following inequalities are always true
12806  print *, huge(i5) >= 10_k5**5-1
12807  print *, huge(i15) >= 10_k15**15-1
12808end program large_integers
12809@end smallexample
12810@end table
12811
12812
12813
12814@node SELECTED_REAL_KIND
12815@section @code{SELECTED_REAL_KIND} --- Choose real kind
12816@fnindex SELECTED_REAL_KIND
12817@cindex real kind
12818@cindex kind, real
12819@cindex radix, real
12820
12821@table @asis
12822@item @emph{Description}:
12823@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12824with decimal precision of at least @code{P} digits, exponent range of
12825at least @code{R}, and with a radix of @code{RADIX}.
12826
12827@item @emph{Standard}:
12828Fortran 90 and later, with @code{RADIX} Fortran 2008 or later
12829
12830@item @emph{Class}:
12831Transformational function
12832
12833@item @emph{Syntax}:
12834@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12835
12836@item @emph{Arguments}:
12837@multitable @columnfractions .15 .70
12838@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12839@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12840@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12841@end multitable
12842Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12843be present; since Fortran 2008, they are assumed to be zero if absent.
12844
12845@item @emph{Return value}:
12846
12847@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12848a real data type with decimal precision of at least @code{P} digits, a
12849decimal exponent range of at least @code{R}, and with the requested
12850@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12851any radix can be returned. If more than one real data type meet the
12852criteria, the kind of the data type with the smallest decimal precision
12853is returned. If no real data type matches the criteria, the result is
12854@table @asis
12855@item -1 if the processor does not support a real data type with a
12856precision greater than or equal to @code{P}, but the @code{R} and
12857@code{RADIX} requirements can be fulfilled
12858@item -2 if the processor does not support a real type with an exponent
12859range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12860are fulfillable
12861@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12862are fulfillable
12863@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12864are fulfillable
12865@item -5 if there is no real type with the given @code{RADIX}
12866@end table
12867
12868@item @emph{Example}:
12869@smallexample
12870program real_kinds
12871  integer,parameter :: p6 = selected_real_kind(6)
12872  integer,parameter :: p10r100 = selected_real_kind(10,100)
12873  integer,parameter :: r400 = selected_real_kind(r=400)
12874  real(kind=p6) :: x
12875  real(kind=p10r100) :: y
12876  real(kind=r400) :: z
12877
12878  print *, precision(x), range(x)
12879  print *, precision(y), range(y)
12880  print *, precision(z), range(z)
12881end program real_kinds
12882@end smallexample
12883@item @emph{See also}:
12884@ref{PRECISION}, @gol
12885@ref{RANGE}, @gol
12886@ref{RADIX}
12887@end table
12888
12889
12890
12891@node SET_EXPONENT
12892@section @code{SET_EXPONENT} --- Set the exponent of the model
12893@fnindex SET_EXPONENT
12894@cindex real number, set exponent
12895@cindex floating point, set exponent
12896
12897@table @asis
12898@item @emph{Description}:
12899@code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12900is that that of @var{X} and whose exponent part is @var{I}.
12901
12902@item @emph{Standard}:
12903Fortran 90 and later
12904
12905@item @emph{Class}:
12906Elemental function
12907
12908@item @emph{Syntax}:
12909@code{RESULT = SET_EXPONENT(X, I)}
12910
12911@item @emph{Arguments}:
12912@multitable @columnfractions .15 .70
12913@item @var{X} @tab Shall be of type @code{REAL}.
12914@item @var{I} @tab Shall be of type @code{INTEGER}.
12915@end multitable
12916
12917@item @emph{Return value}:
12918The return value is of the same type and kind as @var{X}.
12919The real number whose fractional part
12920is that that of @var{X} and whose exponent part if @var{I} is returned;
12921it is @code{FRACTION(X) * RADIX(X)**I}.
12922
12923@item @emph{Example}:
12924@smallexample
12925PROGRAM test_setexp
12926  REAL :: x = 178.1387e-4
12927  INTEGER :: i = 17
12928  PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12929END PROGRAM
12930@end smallexample
12931
12932@end table
12933
12934
12935
12936@node SHAPE
12937@section @code{SHAPE} --- Determine the shape of an array
12938@fnindex SHAPE
12939@cindex array, shape
12940
12941@table @asis
12942@item @emph{Description}:
12943Determines the shape of an array.
12944
12945@item @emph{Standard}:
12946Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12947
12948@item @emph{Class}:
12949Inquiry function
12950
12951@item @emph{Syntax}:
12952@code{RESULT = SHAPE(SOURCE [, KIND])}
12953
12954@item @emph{Arguments}:
12955@multitable @columnfractions .15 .70
12956@item @var{SOURCE} @tab Shall be an array or scalar of any type.
12957If @var{SOURCE} is a pointer it must be associated and allocatable
12958arrays must be allocated.
12959@item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
12960expression indicating the kind parameter of the result.
12961@end multitable
12962
12963@item @emph{Return value}:
12964An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12965has dimensions. The elements of the resulting array correspond to the extend
12966of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12967the result is the rank one array of size zero. If @var{KIND} is absent, the
12968return value has the default integer kind otherwise the specified kind.
12969
12970@item @emph{Example}:
12971@smallexample
12972PROGRAM test_shape
12973  INTEGER, DIMENSION(-1:1, -1:2) :: A
12974  WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
12975  WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
12976END PROGRAM
12977@end smallexample
12978
12979@item @emph{See also}:
12980@ref{RESHAPE}, @gol
12981@ref{SIZE}
12982@end table
12983
12984
12985
12986@node SHIFTA
12987@section @code{SHIFTA} --- Right shift with fill
12988@fnindex SHIFTA
12989@cindex bits, shift right
12990@cindex shift, right with fill
12991
12992@table @asis
12993@item @emph{Description}:
12994@code{SHIFTA} returns a value corresponding to @var{I} with all of the
12995bits shifted right by @var{SHIFT} places.  @var{SHIFT} that be
12996nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
12997the result value is undefined.  Bits shifted out from the right end
12998are lost. The fill is arithmetic: the bits shifted in from the left
12999end are equal to the leftmost bit, which in two's complement
13000representation is the sign bit.
13001
13002@item @emph{Standard}:
13003Fortran 2008 and later
13004
13005@item @emph{Class}:
13006Elemental function
13007
13008@item @emph{Syntax}:
13009@code{RESULT = SHIFTA(I, SHIFT)}
13010
13011@item @emph{Arguments}:
13012@multitable @columnfractions .15 .70
13013@item @var{I} @tab The type shall be @code{INTEGER}.
13014@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13015@end multitable
13016
13017@item @emph{Return value}:
13018The return value is of type @code{INTEGER} and of the same kind as
13019@var{I}.
13020
13021@item @emph{See also}:
13022@ref{SHIFTL}, @gol
13023@ref{SHIFTR}
13024@end table
13025
13026
13027
13028@node SHIFTL
13029@section @code{SHIFTL} --- Left shift
13030@fnindex SHIFTL
13031@cindex bits, shift left
13032@cindex shift, left
13033
13034@table @asis
13035@item @emph{Description}:
13036@code{SHIFTL} returns a value corresponding to @var{I} with all of the
13037bits shifted left by @var{SHIFT} places.  @var{SHIFT} shall be
13038nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13039the result value is undefined.  Bits shifted out from the left end are
13040lost, and bits shifted in from the right end are set to 0.
13041
13042@item @emph{Standard}:
13043Fortran 2008 and later
13044
13045@item @emph{Class}:
13046Elemental function
13047
13048@item @emph{Syntax}:
13049@code{RESULT = SHIFTL(I, SHIFT)}
13050
13051@item @emph{Arguments}:
13052@multitable @columnfractions .15 .70
13053@item @var{I} @tab The type shall be @code{INTEGER}.
13054@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13055@end multitable
13056
13057@item @emph{Return value}:
13058The return value is of type @code{INTEGER} and of the same kind as
13059@var{I}.
13060
13061@item @emph{See also}:
13062@ref{SHIFTA}, @gol
13063@ref{SHIFTR}
13064@end table
13065
13066
13067
13068@node SHIFTR
13069@section @code{SHIFTR} --- Right shift
13070@fnindex SHIFTR
13071@cindex bits, shift right
13072@cindex shift, right
13073
13074@table @asis
13075@item @emph{Description}:
13076@code{SHIFTR} returns a value corresponding to @var{I} with all of the
13077bits shifted right by @var{SHIFT} places.  @var{SHIFT} shall be
13078nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13079the result value is undefined.  Bits shifted out from the right end
13080are lost, and bits shifted in from the left end are set to 0.
13081
13082@item @emph{Standard}:
13083Fortran 2008 and later
13084
13085@item @emph{Class}:
13086Elemental function
13087
13088@item @emph{Syntax}:
13089@code{RESULT = SHIFTR(I, SHIFT)}
13090
13091@item @emph{Arguments}:
13092@multitable @columnfractions .15 .70
13093@item @var{I} @tab The type shall be @code{INTEGER}.
13094@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13095@end multitable
13096
13097@item @emph{Return value}:
13098The return value is of type @code{INTEGER} and of the same kind as
13099@var{I}.
13100
13101@item @emph{See also}:
13102@ref{SHIFTA}, @gol
13103@ref{SHIFTL}
13104@end table
13105
13106
13107
13108@node SIGN
13109@section @code{SIGN} --- Sign copying function
13110@fnindex SIGN
13111@fnindex ISIGN
13112@fnindex DSIGN
13113@cindex sign copying
13114
13115@table @asis
13116@item @emph{Description}:
13117@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
13118
13119@item @emph{Standard}:
13120Fortran 77 and later
13121
13122@item @emph{Class}:
13123Elemental function
13124
13125@item @emph{Syntax}:
13126@code{RESULT = SIGN(A, B)}
13127
13128@item @emph{Arguments}:
13129@multitable @columnfractions .15 .70
13130@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
13131@item @var{B} @tab Shall be of the same type and kind as @var{A}.
13132@end multitable
13133
13134@item @emph{Return value}:
13135The kind of the return value is that of @var{A} and @var{B}.
13136If @math{B \ge 0} then the result is @code{ABS(A)}, else
13137it is @code{-ABS(A)}.
13138
13139@item @emph{Example}:
13140@smallexample
13141program test_sign
13142  print *, sign(-12,1)
13143  print *, sign(-12,0)
13144  print *, sign(-12,-1)
13145
13146  print *, sign(-12.,1.)
13147  print *, sign(-12.,0.)
13148  print *, sign(-12.,-1.)
13149end program test_sign
13150@end smallexample
13151
13152@item @emph{Specific names}:
13153@multitable @columnfractions .20 .26 .20 .30
13154@headitem Name              @tab Arguments              @tab Return type       @tab Standard
13155@item @code{SIGN(A,B)}  @tab @code{REAL(4) A, B}    @tab @code{REAL(4)}    @tab Fortran 77 and later
13156@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later
13157@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B}    @tab @code{REAL(8)}    @tab Fortran 77 and later
13158@end multitable
13159@end table
13160
13161
13162
13163@node SIGNAL
13164@section @code{SIGNAL} --- Signal handling subroutine (or function)
13165@fnindex SIGNAL
13166@cindex system, signal handling
13167
13168@table @asis
13169@item @emph{Description}:
13170@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
13171@var{HANDLER} to be executed with a single integer argument when signal
13172@var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
13173turn off handling of signal @var{NUMBER} or revert to its default
13174action.  See @code{signal(2)}.
13175
13176If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
13177is supplied, it is set to the value returned by @code{signal(2)}.
13178
13179@item @emph{Standard}:
13180GNU extension
13181
13182@item @emph{Class}:
13183Subroutine, function
13184
13185@item @emph{Syntax}:
13186@multitable @columnfractions .80
13187@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
13188@item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
13189@end multitable
13190
13191@item @emph{Arguments}:
13192@multitable @columnfractions .15 .70
13193@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
13194@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
13195@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
13196@code{INTEGER}. It is @code{INTENT(IN)}.
13197@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
13198integer. It has @code{INTENT(OUT)}.
13199@end multitable
13200@c TODO: What should the interface of the handler be?  Does it take arguments?
13201
13202@item @emph{Return value}:
13203The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
13204
13205@item @emph{Example}:
13206@smallexample
13207program test_signal
13208  intrinsic signal
13209  external handler_print
13210
13211  call signal (12, handler_print)
13212  call signal (10, 1)
13213
13214  call sleep (30)
13215end program test_signal
13216@end smallexample
13217@end table
13218
13219
13220
13221@node SIN
13222@section @code{SIN} --- Sine function
13223@fnindex SIN
13224@fnindex DSIN
13225@fnindex CSIN
13226@fnindex ZSIN
13227@fnindex CDSIN
13228@cindex trigonometric function, sine
13229@cindex sine
13230
13231@table @asis
13232@item @emph{Description}:
13233@code{SIN(X)} computes the sine of @var{X}.
13234
13235@item @emph{Standard}:
13236Fortran 77 and later
13237
13238@item @emph{Class}:
13239Elemental function
13240
13241@item @emph{Syntax}:
13242@code{RESULT = SIN(X)}
13243
13244@item @emph{Arguments}:
13245@multitable @columnfractions .15 .70
13246@item @var{X} @tab The type shall be @code{REAL} or
13247@code{COMPLEX}.
13248@end multitable
13249
13250@item @emph{Return value}:
13251The return value has same type and kind as @var{X}.
13252
13253@item @emph{Example}:
13254@smallexample
13255program test_sin
13256  real :: x = 0.0
13257  x = sin(x)
13258end program test_sin
13259@end smallexample
13260
13261@item @emph{Specific names}:
13262@multitable @columnfractions .20 .23 .20 .33
13263@headitem Name            @tab Argument             @tab Return type       @tab Standard
13264@item @code{SIN(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}    @tab Fortran 77 and later
13265@item @code{DSIN(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}    @tab Fortran 77 and later
13266@item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)} @tab Fortran 77 and later
13267@item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab GNU extension
13268@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab GNU extension
13269@end multitable
13270
13271@item @emph{See also}:
13272Inverse function: @gol
13273@ref{ASIN} @gol
13274Degrees function: @gol
13275@ref{SIND}
13276@end table
13277
13278
13279
13280@node SIND
13281@section @code{SIND} --- Sine function, degrees
13282@fnindex SIND
13283@fnindex DSIND
13284@fnindex CSIND
13285@fnindex ZSIND
13286@fnindex CDSIND
13287@cindex trigonometric function, sine, degrees
13288@cindex sine, degrees
13289
13290@table @asis
13291@item @emph{Description}:
13292@code{SIND(X)} computes the sine of @var{X} in degrees.
13293
13294This function is for compatibility only and should be avoided in favor of
13295standard constructs wherever possible.
13296
13297@item @emph{Standard}:
13298GNU extension, enabled with @option{-fdec-math}.
13299
13300@item @emph{Class}:
13301Elemental function
13302
13303@item @emph{Syntax}:
13304@code{RESULT = SIND(X)}
13305
13306@item @emph{Arguments}:
13307@multitable @columnfractions .15 .70
13308@item @var{X} @tab The type shall be @code{REAL} or
13309@code{COMPLEX}.
13310@end multitable
13311
13312@item @emph{Return value}:
13313The return value has same type and kind as @var{X}, and its value is in degrees.
13314
13315@item @emph{Example}:
13316@smallexample
13317program test_sind
13318  real :: x = 0.0
13319  x = sind(x)
13320end program test_sind
13321@end smallexample
13322
13323@item @emph{Specific names}:
13324@multitable @columnfractions .20 .23 .20 .33
13325@headitem Name            @tab Argument             @tab Return type       @tab Standard
13326@item @code{SIND(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}    @tab GNU extension
13327@item @code{DSIND(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}    @tab GNU extension
13328@item @code{CSIND(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)} @tab GNU extension
13329@item @code{ZSIND(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab GNU extension
13330@item @code{CDSIND(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab GNU extension
13331@end multitable
13332
13333@item @emph{See also}:
13334Inverse function: @gol
13335@ref{ASIND} @gol
13336Radians function: @gol
13337@ref{SIN} @gol
13338@end table
13339
13340
13341
13342@node SINH
13343@section @code{SINH} --- Hyperbolic sine function
13344@fnindex SINH
13345@fnindex DSINH
13346@cindex hyperbolic sine
13347@cindex hyperbolic function, sine
13348@cindex sine, hyperbolic
13349
13350@table @asis
13351@item @emph{Description}:
13352@code{SINH(X)} computes the hyperbolic sine of @var{X}.
13353
13354@item @emph{Standard}:
13355Fortran 90 and later, for a complex argument Fortran 2008 or later, has
13356a GNU extension
13357
13358@item @emph{Class}:
13359Elemental function
13360
13361@item @emph{Syntax}:
13362@code{RESULT = SINH(X)}
13363
13364@item @emph{Arguments}:
13365@multitable @columnfractions .15 .70
13366@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13367@end multitable
13368
13369@item @emph{Return value}:
13370The return value has same type and kind as @var{X}.
13371
13372@item @emph{Example}:
13373@smallexample
13374program test_sinh
13375  real(8) :: x = - 1.0_8
13376  x = sinh(x)
13377end program test_sinh
13378@end smallexample
13379
13380@item @emph{Specific names}:
13381@multitable @columnfractions .20 .23 .20 .33
13382@headitem Name            @tab Argument          @tab Return type       @tab Standard
13383@item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 90 and later
13384@end multitable
13385
13386@item @emph{See also}:
13387@ref{ASINH}
13388@end table
13389
13390
13391
13392@node SIZE
13393@section @code{SIZE} --- Determine the size of an array
13394@fnindex SIZE
13395@cindex array, size
13396@cindex array, number of elements
13397@cindex array, count elements
13398
13399@table @asis
13400@item @emph{Description}:
13401Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
13402or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
13403
13404@item @emph{Standard}:
13405Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
13406
13407@item @emph{Class}:
13408Inquiry function
13409
13410@item @emph{Syntax}:
13411@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
13412
13413@item @emph{Arguments}:
13414@multitable @columnfractions .15 .70
13415@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
13416a pointer it must be associated and allocatable arrays must be allocated.
13417@item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER}
13418and its value shall be in the range from 1 to n, where n equals the rank
13419of @var{ARRAY}.
13420@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13421expression indicating the kind parameter of the result.
13422@end multitable
13423
13424@item @emph{Return value}:
13425The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13426@var{KIND} is absent, the return value is of default integer kind.
13427
13428@item @emph{Example}:
13429@smallexample
13430PROGRAM test_size
13431  WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
13432END PROGRAM
13433@end smallexample
13434
13435@item @emph{See also}:
13436@ref{SHAPE}, @gol
13437@ref{RESHAPE}
13438@end table
13439
13440
13441@node SIZEOF
13442@section @code{SIZEOF} --- Size in bytes of an expression
13443@fnindex SIZEOF
13444@cindex expression size
13445@cindex size of an expression
13446
13447@table @asis
13448@item @emph{Description}:
13449@code{SIZEOF(X)} calculates the number of bytes of storage the
13450expression @code{X} occupies.
13451
13452@item @emph{Standard}:
13453GNU extension
13454
13455@item @emph{Class}:
13456Inquiry function
13457
13458@item @emph{Syntax}:
13459@code{N = SIZEOF(X)}
13460
13461@item @emph{Arguments}:
13462@multitable @columnfractions .15 .70
13463@item @var{X} @tab The argument shall be of any type, rank or shape.
13464@end multitable
13465
13466@item @emph{Return value}:
13467The return value is of type integer and of the system-dependent kind
13468@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13469number of bytes occupied by the argument.  If the argument has the
13470@code{POINTER} attribute, the number of bytes of the storage area pointed
13471to is returned.  If the argument is of a derived type with @code{POINTER}
13472or @code{ALLOCATABLE} components, the return value does not account for
13473the sizes of the data pointed to by these components. If the argument is
13474polymorphic, the size according to the dynamic type is returned. The argument
13475may not be a procedure or procedure pointer. Note that the code assumes for
13476arrays that those are contiguous; for contiguous arrays, it returns the
13477storage or an array element multiplied by the size of the array.
13478
13479@item @emph{Example}:
13480@smallexample
13481   integer :: i
13482   real :: r, s(5)
13483   print *, (sizeof(s)/sizeof(r) == 5)
13484   end
13485@end smallexample
13486The example will print @code{.TRUE.} unless you are using a platform
13487where default @code{REAL} variables are unusually padded.
13488
13489@item @emph{See also}:
13490@ref{C_SIZEOF}, @gol
13491@ref{STORAGE_SIZE}
13492@end table
13493
13494
13495@node SLEEP
13496@section @code{SLEEP} --- Sleep for the specified number of seconds
13497@fnindex SLEEP
13498@cindex delayed execution
13499
13500@table @asis
13501@item @emph{Description}:
13502Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13503
13504@item @emph{Standard}:
13505GNU extension
13506
13507@item @emph{Class}:
13508Subroutine
13509
13510@item @emph{Syntax}:
13511@code{CALL SLEEP(SECONDS)}
13512
13513@item @emph{Arguments}:
13514@multitable @columnfractions .15 .70
13515@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13516@end multitable
13517
13518@item @emph{Example}:
13519@smallexample
13520program test_sleep
13521  call sleep(5)
13522end
13523@end smallexample
13524@end table
13525
13526
13527
13528@node SPACING
13529@section @code{SPACING} --- Smallest distance between two numbers of a given type
13530@fnindex SPACING
13531@cindex real number, relative spacing
13532@cindex floating point, relative spacing
13533
13534@table @asis
13535@item @emph{Description}:
13536Determines the distance between the argument @var{X} and the nearest
13537adjacent number of the same type.
13538
13539@item @emph{Standard}:
13540Fortran 90 and later
13541
13542@item @emph{Class}:
13543Elemental function
13544
13545@item @emph{Syntax}:
13546@code{RESULT = SPACING(X)}
13547
13548@item @emph{Arguments}:
13549@multitable @columnfractions .15 .70
13550@item @var{X} @tab Shall be of type @code{REAL}.
13551@end multitable
13552
13553@item @emph{Return value}:
13554The result is of the same type as the input argument @var{X}.
13555
13556@item @emph{Example}:
13557@smallexample
13558PROGRAM test_spacing
13559  INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13560  INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13561
13562  WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
13563  WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
13564END PROGRAM
13565@end smallexample
13566
13567@item @emph{See also}:
13568@ref{RRSPACING}
13569@end table
13570
13571
13572
13573@node SPREAD
13574@section @code{SPREAD} --- Add a dimension to an array
13575@fnindex SPREAD
13576@cindex array, increase dimension
13577@cindex array, duplicate elements
13578@cindex array, duplicate dimensions
13579
13580@table @asis
13581@item @emph{Description}:
13582Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13583dimension @var{DIM}.
13584
13585@item @emph{Standard}:
13586Fortran 90 and later
13587
13588@item @emph{Class}:
13589Transformational function
13590
13591@item @emph{Syntax}:
13592@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13593
13594@item @emph{Arguments}:
13595@multitable @columnfractions .15 .70
13596@item @var{SOURCE}  @tab Shall be a scalar or an array of any type and
13597a rank less than seven.
13598@item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a
13599value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13600@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13601@end multitable
13602
13603@item @emph{Return value}:
13604The result is an array of the same type as @var{SOURCE} and has rank n+1
13605where n equals the rank of @var{SOURCE}.
13606
13607@item @emph{Example}:
13608@smallexample
13609PROGRAM test_spread
13610  INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13611  WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
13612  WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
13613END PROGRAM
13614@end smallexample
13615
13616@item @emph{See also}:
13617@ref{UNPACK}
13618@end table
13619
13620
13621
13622@node SQRT
13623@section @code{SQRT} --- Square-root function
13624@fnindex SQRT
13625@fnindex DSQRT
13626@fnindex CSQRT
13627@fnindex ZSQRT
13628@fnindex CDSQRT
13629@cindex root
13630@cindex square-root
13631
13632@table @asis
13633@item @emph{Description}:
13634@code{SQRT(X)} computes the square root of @var{X}.
13635
13636@item @emph{Standard}:
13637Fortran 77 and later
13638
13639@item @emph{Class}:
13640Elemental function
13641
13642@item @emph{Syntax}:
13643@code{RESULT = SQRT(X)}
13644
13645@item @emph{Arguments}:
13646@multitable @columnfractions .15 .70
13647@item @var{X} @tab The type shall be @code{REAL} or
13648@code{COMPLEX}.
13649@end multitable
13650
13651@item @emph{Return value}:
13652The return value is of type @code{REAL} or @code{COMPLEX}.
13653The kind type parameter is the same as @var{X}.
13654
13655@item @emph{Example}:
13656@smallexample
13657program test_sqrt
13658  real(8) :: x = 2.0_8
13659  complex :: z = (1.0, 2.0)
13660  x = sqrt(x)
13661  z = sqrt(z)
13662end program test_sqrt
13663@end smallexample
13664
13665@item @emph{Specific names}:
13666@multitable @columnfractions .20 .23 .20 .33
13667@headitem Name             @tab Argument             @tab Return type          @tab Standard
13668@item @code{SQRT(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}       @tab Fortran 77 and later
13669@item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab Fortran 77 and later
13670@item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 77 and later
13671@item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
13672@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
13673@end multitable
13674@end table
13675
13676
13677
13678@node SRAND
13679@section @code{SRAND} --- Reinitialize the random number generator
13680@fnindex SRAND
13681@cindex random number generation, seeding
13682@cindex seeding a random number generator
13683
13684@table @asis
13685@item @emph{Description}:
13686@code{SRAND} reinitializes the pseudo-random number generator
13687called by @code{RAND} and @code{IRAND}. The new seed used by the
13688generator is specified by the required argument @var{SEED}.
13689
13690@item @emph{Standard}:
13691GNU extension
13692
13693@item @emph{Class}:
13694Subroutine
13695
13696@item @emph{Syntax}:
13697@code{CALL SRAND(SEED)}
13698
13699@item @emph{Arguments}:
13700@multitable @columnfractions .15 .70
13701@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13702@end multitable
13703
13704@item @emph{Return value}:
13705Does not return anything.
13706
13707@item @emph{Example}:
13708See @code{RAND} and @code{IRAND} for examples.
13709
13710@item @emph{Notes}:
13711The Fortran standard specifies the intrinsic subroutines
13712@code{RANDOM_SEED} to initialize the pseudo-random number
13713generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13714These subroutines should be used in new codes.
13715
13716Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13717@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13718@code{RANDOM_SEED} on the other hand) access two independent
13719pseudo-random number generators.
13720
13721@item @emph{See also}:
13722@ref{RAND}, @gol
13723@ref{RANDOM_SEED}, @gol
13724@ref{RANDOM_NUMBER}
13725@end table
13726
13727
13728
13729@node STAT
13730@section @code{STAT} --- Get file status
13731@fnindex STAT
13732@cindex file system, file status
13733
13734@table @asis
13735@item @emph{Description}:
13736This function returns information about a file. No permissions are required on
13737the file itself, but execute (search) permission is required on all of the
13738directories in path that lead to the file.
13739
13740The elements that are obtained and stored in the array @code{VALUES}:
13741@multitable @columnfractions .15 .70
13742@item @code{VALUES(1)}   @tab  Device ID
13743@item @code{VALUES(2)}   @tab  Inode number
13744@item @code{VALUES(3)}   @tab  File mode
13745@item @code{VALUES(4)}   @tab  Number of links
13746@item @code{VALUES(5)}   @tab  Owner's uid
13747@item @code{VALUES(6)}   @tab  Owner's gid
13748@item @code{VALUES(7)}   @tab  ID of device containing directory entry for file (0 if not available)
13749@item @code{VALUES(8)}   @tab  File size (bytes)
13750@item @code{VALUES(9)}   @tab  Last access time
13751@item @code{VALUES(10)}  @tab  Last modification time
13752@item @code{VALUES(11)}  @tab  Last file status change time
13753@item @code{VALUES(12)}  @tab  Preferred I/O block size (-1 if not available)
13754@item @code{VALUES(13)}  @tab  Number of blocks allocated (-1 if not available)
13755@end multitable
13756
13757Not all these elements are relevant on all systems.
13758If an element is not relevant, it is returned as 0.
13759
13760This intrinsic is provided in both subroutine and function forms; however,
13761only one form can be used in any given program unit.
13762
13763@item @emph{Standard}:
13764GNU extension
13765
13766@item @emph{Class}:
13767Subroutine, function
13768
13769@item @emph{Syntax}:
13770@multitable @columnfractions .80
13771@item @code{CALL STAT(NAME, VALUES [, STATUS])}
13772@item @code{STATUS = STAT(NAME, VALUES)}
13773@end multitable
13774
13775@item @emph{Arguments}:
13776@multitable @columnfractions .15 .70
13777@item @var{NAME}   @tab The type shall be @code{CHARACTER}, of the
13778default kind and a valid path within the file system.
13779@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13780@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13781on success and a system specific error code otherwise.
13782@end multitable
13783
13784@item @emph{Example}:
13785@smallexample
13786PROGRAM test_stat
13787  INTEGER, DIMENSION(13) :: buff
13788  INTEGER :: status
13789
13790  CALL STAT("/etc/passwd", buff, status)
13791
13792  IF (status == 0) THEN
13793    WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
13794    WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
13795    WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
13796    WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
13797    WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
13798    WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
13799    WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
13800    WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
13801    WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
13802    WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
13803    WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13804    WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
13805    WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13806  END IF
13807END PROGRAM
13808@end smallexample
13809
13810@item @emph{See also}:
13811To stat an open file: @gol
13812@ref{FSTAT} @gol
13813To stat a link: @gol
13814@ref{LSTAT}
13815@end table
13816
13817
13818
13819@node STORAGE_SIZE
13820@section @code{STORAGE_SIZE} --- Storage size in bits
13821@fnindex STORAGE_SIZE
13822@cindex storage size
13823
13824@table @asis
13825@item @emph{Description}:
13826Returns the storage size of argument @var{A} in bits.
13827@item @emph{Standard}:
13828Fortran 2008 and later
13829@item @emph{Class}:
13830Inquiry function
13831@item @emph{Syntax}:
13832@code{RESULT = STORAGE_SIZE(A [, KIND])}
13833
13834@item @emph{Arguments}:
13835@multitable @columnfractions .15 .70
13836@item @var{A} @tab Shall be a scalar or array of any type.
13837@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13838@end multitable
13839
13840@item @emph{Return Value}:
13841The result is a scalar integer with the kind type parameter specified by KIND
13842(or default integer type if KIND is missing). The result value is the size
13843expressed in bits for an element of an array that has the dynamic type and type
13844parameters of A.
13845
13846@item @emph{See also}:
13847@ref{C_SIZEOF}, @gol
13848@ref{SIZEOF}
13849@end table
13850
13851
13852
13853@node SUM
13854@section @code{SUM} --- Sum of array elements
13855@fnindex SUM
13856@cindex array, sum
13857@cindex array, add elements
13858@cindex array, conditionally add elements
13859@cindex sum array elements
13860
13861@table @asis
13862@item @emph{Description}:
13863Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13864the corresponding element in @var{MASK} is @code{TRUE}.
13865
13866@item @emph{Standard}:
13867Fortran 90 and later
13868
13869@item @emph{Class}:
13870Transformational function
13871
13872@item @emph{Syntax}:
13873@multitable @columnfractions .80
13874@item @code{RESULT = SUM(ARRAY[, MASK])}
13875@item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13876@end multitable
13877
13878@item @emph{Arguments}:
13879@multitable @columnfractions .15 .70
13880@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13881@code{REAL} or @code{COMPLEX}.
13882@item @var{DIM}   @tab (Optional) shall be a scalar of type
13883@code{INTEGER} with a value in the range from 1 to n, where n
13884equals the rank of @var{ARRAY}.
13885@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
13886and either be a scalar or an array of the same shape as @var{ARRAY}.
13887@end multitable
13888
13889@item @emph{Return value}:
13890The result is of the same type as @var{ARRAY}.
13891
13892If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13893is returned. Otherwise, an array of rank n-1, where n equals the rank of
13894@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13895dropped is returned.
13896
13897@item @emph{Example}:
13898@smallexample
13899PROGRAM test_sum
13900  INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13901  print *, SUM(x)                        ! all elements, sum = 15
13902  print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
13903END PROGRAM
13904@end smallexample
13905
13906@item @emph{See also}:
13907@ref{PRODUCT}
13908@end table
13909
13910
13911
13912@node SYMLNK
13913@section @code{SYMLNK} --- Create a symbolic link
13914@fnindex SYMLNK
13915@cindex file system, create link
13916@cindex file system, soft link
13917
13918@table @asis
13919@item @emph{Description}:
13920Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13921character (@code{CHAR(0)}) can be used to mark the end of the names in
13922@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13923names are ignored.  If the @var{STATUS} argument is supplied, it
13924contains 0 on success or a nonzero error code upon return; see
13925@code{symlink(2)}.  If the system does not supply @code{symlink(2)},
13926@code{ENOSYS} is returned.
13927
13928This intrinsic is provided in both subroutine and function forms;
13929however, only one form can be used in any given program unit.
13930
13931@item @emph{Standard}:
13932GNU extension
13933
13934@item @emph{Class}:
13935Subroutine, function
13936
13937@item @emph{Syntax}:
13938@multitable @columnfractions .80
13939@item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13940@item @code{STATUS = SYMLNK(PATH1, PATH2)}
13941@end multitable
13942
13943@item @emph{Arguments}:
13944@multitable @columnfractions .15 .70
13945@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13946@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13947@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13948@end multitable
13949
13950@item @emph{See also}:
13951@ref{LINK}, @gol
13952@ref{UNLINK}
13953@end table
13954
13955
13956
13957@node SYSTEM
13958@section @code{SYSTEM} --- Execute a shell command
13959@fnindex SYSTEM
13960@cindex system, system call
13961
13962@table @asis
13963@item @emph{Description}:
13964Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13965argument @var{STATUS} is present, it contains the value returned by
13966@code{system(3)}, which is presumably 0 if the shell command succeeded.
13967Note that which shell is used to invoke the command is system-dependent
13968and environment-dependent.
13969
13970This intrinsic is provided in both subroutine and function forms;
13971however, only one form can be used in any given program unit.
13972
13973Note that the @code{system} function need not be thread-safe. It is
13974the responsibility of the user to ensure that @code{system} is not
13975called concurrently.
13976
13977@item @emph{Standard}:
13978GNU extension
13979
13980@item @emph{Class}:
13981Subroutine, function
13982
13983@item @emph{Syntax}:
13984@multitable @columnfractions .80
13985@item @code{CALL SYSTEM(COMMAND [, STATUS])}
13986@item @code{STATUS = SYSTEM(COMMAND)}
13987@end multitable
13988
13989@item @emph{Arguments}:
13990@multitable @columnfractions .15 .70
13991@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13992@item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
13993@end multitable
13994
13995@item @emph{See also}:
13996@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13997and should considered in new code for future portability.
13998@end table
13999
14000
14001
14002@node SYSTEM_CLOCK
14003@section @code{SYSTEM_CLOCK} --- Time function
14004@fnindex SYSTEM_CLOCK
14005@cindex time, clock ticks
14006@cindex clock ticks
14007
14008@table @asis
14009@item @emph{Description}:
14010Determines the @var{COUNT} of a processor clock since an unspecified
14011time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
14012the number of clock ticks per second.  If the platform supports a
14013monotonic clock, that clock is used and can, depending on the platform
14014clock implementation, provide up to nanosecond resolution.  If a
14015monotonic clock is not available, the implementation falls back to a
14016realtime clock.
14017
14018@var{COUNT_RATE} is system dependent and can vary depending on the kind of
14019the arguments. For @var{kind=4} arguments (and smaller integer kinds),
14020@var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
14021larger integer kinds), @var{COUNT} typically represents micro- or
14022nanoseconds depending on resolution of the underlying platform clock.
14023@var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
14024millisecond resolution of the @var{kind=4} version implies that the
14025@var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
14026with the wrap around and for more precise timing, please use the
14027@var{kind=8} version.
14028
14029If there is no clock, or querying the clock fails, @var{COUNT} is set
14030to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
14031set to zero.
14032
14033When running on a platform using the GNU C library (glibc) version
140342.16 or older, or a derivative thereof, the high resolution monotonic
14035clock is available only when linking with the @var{rt} library.  This
14036can be done explicitly by adding the @code{-lrt} flag when linking the
14037application, but is also done implicitly when using OpenMP.
14038
14039On the Windows platform, the version with @var{kind=4} arguments uses
14040the @code{GetTickCount} function, whereas the @var{kind=8} version
14041uses @code{QueryPerformanceCounter} and
14042@code{QueryPerformanceCounterFrequency}. For more information, and
14043potential caveats, please see the platform documentation.
14044
14045@item @emph{Standard}:
14046Fortran 90 and later
14047
14048@item @emph{Class}:
14049Subroutine
14050
14051@item @emph{Syntax}:
14052@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
14053
14054@item @emph{Arguments}:
14055@multitable @columnfractions .20 .65
14056@item @var{COUNT}      @tab (Optional) shall be a scalar of type
14057@code{INTEGER} with @code{INTENT(OUT)}.
14058@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
14059@code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
14060@item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type
14061@code{INTEGER} with @code{INTENT(OUT)}.
14062@end multitable
14063
14064@item @emph{Example}:
14065@smallexample
14066PROGRAM test_system_clock
14067  INTEGER :: count, count_rate, count_max
14068  CALL SYSTEM_CLOCK(count, count_rate, count_max)
14069  WRITE(*,*) count, count_rate, count_max
14070END PROGRAM
14071@end smallexample
14072
14073@item @emph{See also}:
14074@ref{DATE_AND_TIME}, @gol
14075@ref{CPU_TIME}
14076@end table
14077
14078
14079
14080@node TAN
14081@section @code{TAN} --- Tangent function
14082@fnindex TAN
14083@fnindex DTAN
14084@cindex trigonometric function, tangent
14085@cindex tangent
14086
14087@table @asis
14088@item @emph{Description}:
14089@code{TAN(X)} computes the tangent of @var{X}.
14090
14091@item @emph{Standard}:
14092Fortran 77 and later, for a complex argument Fortran 2008 or later
14093
14094@item @emph{Class}:
14095Elemental function
14096
14097@item @emph{Syntax}:
14098@code{RESULT = TAN(X)}
14099
14100@item @emph{Arguments}:
14101@multitable @columnfractions .15 .70
14102@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14103@end multitable
14104
14105@item @emph{Return value}:
14106The return value has same type and kind as @var{X}, and its value is in radians.
14107
14108@item @emph{Example}:
14109@smallexample
14110program test_tan
14111  real(8) :: x = 0.165_8
14112  x = tan(x)
14113end program test_tan
14114@end smallexample
14115
14116@item @emph{Specific names}:
14117@multitable @columnfractions .20 .23 .20 .33
14118@headitem Name            @tab Argument          @tab Return type     @tab Standard
14119@item @code{TAN(X)}   @tab @code{REAL(4) X}  @tab @code{REAL(4)}  @tab Fortran 77 and later
14120@item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab Fortran 77 and later
14121@end multitable
14122
14123@item @emph{See also}:
14124Inverse function: @gol
14125@ref{ATAN} @gol
14126Degrees function: @gol
14127@ref{TAND}
14128@end table
14129
14130
14131
14132@node TAND
14133@section @code{TAND} --- Tangent function, degrees
14134@fnindex TAND
14135@fnindex DTAND
14136@cindex trigonometric function, tangent, degrees
14137@cindex tangent, degrees
14138
14139@table @asis
14140@item @emph{Description}:
14141@code{TAND(X)} computes the tangent of @var{X} in degrees.
14142
14143This function is for compatibility only and should be avoided in favor of
14144standard constructs wherever possible.
14145
14146@item @emph{Standard}:
14147GNU extension, enabled with @option{-fdec-math}.
14148
14149@item @emph{Class}:
14150Elemental function
14151
14152@item @emph{Syntax}:
14153@code{RESULT = TAND(X)}
14154
14155@item @emph{Arguments}:
14156@multitable @columnfractions .15 .70
14157@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14158@end multitable
14159
14160@item @emph{Return value}:
14161The return value has same type and kind as @var{X}, and its value is in degrees.
14162
14163@item @emph{Example}:
14164@smallexample
14165program test_tand
14166  real(8) :: x = 0.165_8
14167  x = tand(x)
14168end program test_tand
14169@end smallexample
14170
14171@item @emph{Specific names}:
14172@multitable @columnfractions .20 .23 .20 .33
14173@headitem Name            @tab Argument          @tab Return type     @tab Standard
14174@item @code{TAND(X)}   @tab @code{REAL(4) X}  @tab @code{REAL(4)}  @tab GNU extension
14175@item @code{DTAND(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab GNU extension
14176@end multitable
14177
14178@item @emph{See also}:
14179Inverse function: @gol
14180@ref{ATAND} @gol
14181Radians function: @gol
14182@ref{TAN}
14183@end table
14184
14185
14186
14187@node TANH
14188@section @code{TANH} --- Hyperbolic tangent function
14189@fnindex TANH
14190@fnindex DTANH
14191@cindex hyperbolic tangent
14192@cindex hyperbolic function, tangent
14193@cindex tangent, hyperbolic
14194
14195@table @asis
14196@item @emph{Description}:
14197@code{TANH(X)} computes the hyperbolic tangent of @var{X}.
14198
14199@item @emph{Standard}:
14200Fortran 77 and later, for a complex argument Fortran 2008 or later
14201
14202@item @emph{Class}:
14203Elemental function
14204
14205@item @emph{Syntax}:
14206@code{X = TANH(X)}
14207
14208@item @emph{Arguments}:
14209@multitable @columnfractions .15 .70
14210@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14211@end multitable
14212
14213@item @emph{Return value}:
14214The return value has same type and kind as @var{X}. If @var{X} is
14215complex, the imaginary part of the result is in radians. If @var{X}
14216is @code{REAL}, the return value lies in the range
14217@math{ - 1 \leq tanh(x) \leq 1 }.
14218
14219@item @emph{Example}:
14220@smallexample
14221program test_tanh
14222  real(8) :: x = 2.1_8
14223  x = tanh(x)
14224end program test_tanh
14225@end smallexample
14226
14227@item @emph{Specific names}:
14228@multitable @columnfractions .20 .23 .20 .33
14229@headitem Name            @tab Argument          @tab Return type       @tab Standard
14230@item @code{TANH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
14231@item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
14232@end multitable
14233
14234@item @emph{See also}:
14235@ref{ATANH}
14236@end table
14237
14238
14239
14240@node THIS_IMAGE
14241@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
14242@fnindex THIS_IMAGE
14243@cindex coarray, @code{THIS_IMAGE}
14244@cindex images, index of this image
14245
14246@table @asis
14247@item @emph{Description}:
14248Returns the cosubscript for this image.
14249
14250@item @emph{Standard}:
14251Fortran 2008 and later. With @var{DISTANCE} argument,
14252Technical Specification (TS) 18508 or later
14253
14254@item @emph{Class}:
14255Transformational function
14256
14257@item @emph{Syntax}:
14258@multitable @columnfractions .80
14259@item @code{RESULT = THIS_IMAGE()}
14260@item @code{RESULT = THIS_IMAGE(DISTANCE)}
14261@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
14262@end multitable
14263
14264@item @emph{Arguments}:
14265@multitable @columnfractions .15 .70
14266@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
14267(not permitted together with @var{COARRAY}).
14268@item @var{COARRAY} @tab Coarray of any type  (optional; if @var{DIM}
14269present, required).
14270@item @var{DIM}     @tab default integer scalar (optional). If present,
14271@var{DIM} shall be between one and the corank of @var{COARRAY}.
14272@end multitable
14273
14274
14275@item @emph{Return value}:
14276Default integer. If @var{COARRAY} is not present, it is scalar; if
14277@var{DISTANCE} is not present or has value 0, its value is the image index on
14278the invoking image for the current team, for values smaller or equal
14279distance to the initial team, it returns the image index on the ancestor team
14280which has a distance of @var{DISTANCE} from the invoking team. If
14281@var{DISTANCE} is larger than the distance to the initial team, the image
14282index of the initial team is returned. Otherwise when the @var{COARRAY} is
14283present, if @var{DIM} is not present, a rank-1 array with corank elements is
14284returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
14285image. If @var{DIM} is present, a scalar is returned, with the value of
14286the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
14287
14288@item @emph{Example}:
14289@smallexample
14290INTEGER :: value[*]
14291INTEGER :: i
14292value = THIS_IMAGE()
14293SYNC ALL
14294IF (THIS_IMAGE() == 1) THEN
14295  DO i = 1, NUM_IMAGES()
14296    WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
14297  END DO
14298END IF
14299
14300! Check whether the current image is the initial image
14301IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
14302  error stop "something is rotten here"
14303@end smallexample
14304
14305@item @emph{See also}:
14306@ref{NUM_IMAGES}, @gol
14307@ref{IMAGE_INDEX}
14308@end table
14309
14310
14311
14312@node TIME
14313@section @code{TIME} --- Time function
14314@fnindex TIME
14315@cindex time, current
14316@cindex current time
14317
14318@table @asis
14319@item @emph{Description}:
14320Returns the current time encoded as an integer (in the manner of the
14321function @code{time(3)} in the C standard library). This value is
14322suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14323
14324This intrinsic is not fully portable, such as to systems with 32-bit
14325@code{INTEGER} types but supporting times wider than 32 bits. Therefore,
14326the values returned by this intrinsic might be, or become, negative, or
14327numerically less than previous values, during a single run of the
14328compiled program.
14329
14330See @ref{TIME8}, for information on a similar intrinsic that might be
14331portable to more GNU Fortran implementations, though to fewer Fortran
14332compilers.
14333
14334@item @emph{Standard}:
14335GNU extension
14336
14337@item @emph{Class}:
14338Function
14339
14340@item @emph{Syntax}:
14341@code{RESULT = TIME()}
14342
14343@item @emph{Return value}:
14344The return value is a scalar of type @code{INTEGER(4)}.
14345
14346@item @emph{See also}:
14347@ref{DATE_AND_TIME}, @gol
14348@ref{CTIME}, @gol
14349@ref{GMTIME}, @gol
14350@ref{LTIME}, @gol
14351@ref{MCLOCK}, @gol
14352@ref{TIME8}
14353@end table
14354
14355
14356
14357@node TIME8
14358@section @code{TIME8} --- Time function (64-bit)
14359@fnindex TIME8
14360@cindex time, current
14361@cindex current time
14362
14363@table @asis
14364@item @emph{Description}:
14365Returns the current time encoded as an integer (in the manner of the
14366function @code{time(3)} in the C standard library). This value is
14367suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14368
14369@emph{Warning:} this intrinsic does not increase the range of the timing
14370values over that returned by @code{time(3)}. On a system with a 32-bit
14371@code{time(3)}, @code{TIME8} will return a 32-bit value, even though
14372it is converted to a 64-bit @code{INTEGER(8)} value. That means
14373overflows of the 32-bit value can still occur. Therefore, the values
14374returned by this intrinsic might be or become negative or numerically
14375less than previous values during a single run of the compiled program.
14376
14377@item @emph{Standard}:
14378GNU extension
14379
14380@item @emph{Class}:
14381Function
14382
14383@item @emph{Syntax}:
14384@code{RESULT = TIME8()}
14385
14386@item @emph{Return value}:
14387The return value is a scalar of type @code{INTEGER(8)}.
14388
14389@item @emph{See also}:
14390@ref{DATE_AND_TIME}, @gol
14391@ref{CTIME}, @gol
14392@ref{GMTIME}, @gol
14393@ref{LTIME}, @gol
14394@ref{MCLOCK8}, @gol
14395@ref{TIME}
14396@end table
14397
14398
14399
14400@node TINY
14401@section @code{TINY} --- Smallest positive number of a real kind
14402@fnindex TINY
14403@cindex limits, smallest number
14404@cindex model representation, smallest number
14405
14406@table @asis
14407@item @emph{Description}:
14408@code{TINY(X)} returns the smallest positive (non zero) number
14409in the model of the type of @code{X}.
14410
14411@item @emph{Standard}:
14412Fortran 90 and later
14413
14414@item @emph{Class}:
14415Inquiry function
14416
14417@item @emph{Syntax}:
14418@code{RESULT = TINY(X)}
14419
14420@item @emph{Arguments}:
14421@multitable @columnfractions .15 .70
14422@item @var{X} @tab Shall be of type @code{REAL}.
14423@end multitable
14424
14425@item @emph{Return value}:
14426The return value is of the same type and kind as @var{X}
14427
14428@item @emph{Example}:
14429See @code{HUGE} for an example.
14430@end table
14431
14432
14433
14434@node TRAILZ
14435@section @code{TRAILZ} --- Number of trailing zero bits of an integer
14436@fnindex TRAILZ
14437@cindex zero bits
14438
14439@table @asis
14440@item @emph{Description}:
14441@code{TRAILZ} returns the number of trailing zero bits of an integer.
14442
14443@item @emph{Standard}:
14444Fortran 2008 and later
14445
14446@item @emph{Class}:
14447Elemental function
14448
14449@item @emph{Syntax}:
14450@code{RESULT = TRAILZ(I)}
14451
14452@item @emph{Arguments}:
14453@multitable @columnfractions .15 .70
14454@item @var{I} @tab Shall be of type @code{INTEGER}.
14455@end multitable
14456
14457@item @emph{Return value}:
14458The type of the return value is the default @code{INTEGER}.
14459If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
14460
14461@item @emph{Example}:
14462@smallexample
14463PROGRAM test_trailz
14464  WRITE (*,*) TRAILZ(8)  ! prints 3
14465END PROGRAM
14466@end smallexample
14467
14468@item @emph{See also}:
14469@ref{BIT_SIZE}, @gol
14470@ref{LEADZ}, @gol
14471@ref{POPPAR}, @gol
14472@ref{POPCNT}
14473@end table
14474
14475
14476
14477@node TRANSFER
14478@section @code{TRANSFER} --- Transfer bit patterns
14479@fnindex TRANSFER
14480@cindex bits, move
14481@cindex type cast
14482
14483@table @asis
14484@item @emph{Description}:
14485Interprets the bitwise representation of @var{SOURCE} in memory as if it
14486is the representation of a variable or array of the same type and type
14487parameters as @var{MOLD}.
14488
14489This is approximately equivalent to the C concept of @emph{casting} one
14490type to another.
14491
14492@item @emph{Standard}:
14493Fortran 90 and later
14494
14495@item @emph{Class}:
14496Transformational function
14497
14498@item @emph{Syntax}:
14499@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14500
14501@item @emph{Arguments}:
14502@multitable @columnfractions .15 .70
14503@item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14504@item @var{MOLD}   @tab Shall be a scalar or an array of any type.
14505@item @var{SIZE}   @tab (Optional) shall be a scalar of type
14506@code{INTEGER}.
14507@end multitable
14508
14509@item @emph{Return value}:
14510The result has the same type as @var{MOLD}, with the bit level
14511representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
14512a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
14513but @var{MOLD} is an array (of any size or shape), the result is a one-
14514dimensional array of the minimum length needed to contain the entirety
14515of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
14516and @var{MOLD} is a scalar, the result is a scalar.
14517
14518If the bitwise representation of the result is longer than that of
14519@var{SOURCE}, then the leading bits of the result correspond to those of
14520@var{SOURCE} and any trailing bits are filled arbitrarily.
14521
14522When the resulting bit representation does not correspond to a valid
14523representation of a variable of the same type as @var{MOLD}, the results
14524are undefined, and subsequent operations on the result cannot be
14525guaranteed to produce sensible behavior.  For example, it is possible to
14526create @code{LOGICAL} variables for which @code{@var{VAR}} and
14527@code{.NOT.@var{VAR}} both appear to be true.
14528
14529@item @emph{Example}:
14530@smallexample
14531PROGRAM test_transfer
14532  integer :: x = 2143289344
14533  print *, transfer(x, 1.0)    ! prints "NaN" on i686
14534END PROGRAM
14535@end smallexample
14536@end table
14537
14538
14539
14540@node TRANSPOSE
14541@section @code{TRANSPOSE} --- Transpose an array of rank two
14542@fnindex TRANSPOSE
14543@cindex array, transpose
14544@cindex matrix, transpose
14545@cindex transpose
14546
14547@table @asis
14548@item @emph{Description}:
14549Transpose an array of rank two. Element (i, j) of the result has the value
14550@code{MATRIX(j, i)}, for all i, j.
14551
14552@item @emph{Standard}:
14553Fortran 90 and later
14554
14555@item @emph{Class}:
14556Transformational function
14557
14558@item @emph{Syntax}:
14559@code{RESULT = TRANSPOSE(MATRIX)}
14560
14561@item @emph{Arguments}:
14562@multitable @columnfractions .15 .70
14563@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14564@end multitable
14565
14566@item @emph{Return value}:
14567The result has the same type as @var{MATRIX}, and has shape
14568@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14569@end table
14570
14571
14572
14573@node TRIM
14574@section @code{TRIM} --- Remove trailing blank characters of a string
14575@fnindex TRIM
14576@cindex string, remove trailing whitespace
14577
14578@table @asis
14579@item @emph{Description}:
14580Removes trailing blank characters of a string.
14581
14582@item @emph{Standard}:
14583Fortran 90 and later
14584
14585@item @emph{Class}:
14586Transformational function
14587
14588@item @emph{Syntax}:
14589@code{RESULT = TRIM(STRING)}
14590
14591@item @emph{Arguments}:
14592@multitable @columnfractions .15 .70
14593@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14594@end multitable
14595
14596@item @emph{Return value}:
14597A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14598less the number of trailing blanks.
14599
14600@item @emph{Example}:
14601@smallexample
14602PROGRAM test_trim
14603  CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
14604  WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
14605END PROGRAM
14606@end smallexample
14607
14608@item @emph{See also}:
14609@ref{ADJUSTL}, @gol
14610@ref{ADJUSTR}
14611@end table
14612
14613
14614
14615@node TTYNAM
14616@section @code{TTYNAM} --- Get the name of a terminal device.
14617@fnindex TTYNAM
14618@cindex system, terminal
14619
14620@table @asis
14621@item @emph{Description}:
14622Get the name of a terminal device. For more information,
14623see @code{ttyname(3)}.
14624
14625This intrinsic is provided in both subroutine and function forms;
14626however, only one form can be used in any given program unit.
14627
14628@item @emph{Standard}:
14629GNU extension
14630
14631@item @emph{Class}:
14632Subroutine, function
14633
14634@item @emph{Syntax}:
14635@multitable @columnfractions .80
14636@item @code{CALL TTYNAM(UNIT, NAME)}
14637@item @code{NAME = TTYNAM(UNIT)}
14638@end multitable
14639
14640@item @emph{Arguments}:
14641@multitable @columnfractions .15 .70
14642@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14643@item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14644@end multitable
14645
14646@item @emph{Example}:
14647@smallexample
14648PROGRAM test_ttynam
14649  INTEGER :: unit
14650  DO unit = 1, 10
14651    IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14652  END DO
14653END PROGRAM
14654@end smallexample
14655
14656@item @emph{See also}:
14657@ref{ISATTY}
14658@end table
14659
14660
14661
14662@node UBOUND
14663@section @code{UBOUND} --- Upper dimension bounds of an array
14664@fnindex UBOUND
14665@cindex array, upper bound
14666
14667@table @asis
14668@item @emph{Description}:
14669Returns the upper bounds of an array, or a single upper bound
14670along the @var{DIM} dimension.
14671@item @emph{Standard}:
14672Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14673
14674@item @emph{Class}:
14675Inquiry function
14676
14677@item @emph{Syntax}:
14678@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14679
14680@item @emph{Arguments}:
14681@multitable @columnfractions .15 .70
14682@item @var{ARRAY} @tab Shall be an array, of any type.
14683@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14684@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
14685expression indicating the kind parameter of the result.
14686@end multitable
14687
14688@item @emph{Return value}:
14689The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14690@var{KIND} is absent, the return value is of default integer kind.
14691If @var{DIM} is absent, the result is an array of the upper bounds of
14692@var{ARRAY}.  If @var{DIM} is present, the result is a scalar
14693corresponding to the upper bound of the array along that dimension.  If
14694@var{ARRAY} is an expression rather than a whole array or array
14695structure component, or if it has a zero extent along the relevant
14696dimension, the upper bound is taken to be the number of elements along
14697the relevant dimension.
14698
14699@item @emph{See also}:
14700@ref{LBOUND}, @gol
14701@ref{LCOBOUND}
14702@end table
14703
14704
14705
14706@node UCOBOUND
14707@section @code{UCOBOUND} --- Upper codimension bounds of an array
14708@fnindex UCOBOUND
14709@cindex coarray, upper bound
14710
14711@table @asis
14712@item @emph{Description}:
14713Returns the upper cobounds of a coarray, or a single upper cobound
14714along the @var{DIM} codimension.
14715@item @emph{Standard}:
14716Fortran 2008 and later
14717
14718@item @emph{Class}:
14719Inquiry function
14720
14721@item @emph{Syntax}:
14722@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14723
14724@item @emph{Arguments}:
14725@multitable @columnfractions .15 .70
14726@item @var{ARRAY} @tab Shall be an coarray, of any type.
14727@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14728@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14729expression indicating the kind parameter of the result.
14730@end multitable
14731
14732@item @emph{Return value}:
14733The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14734@var{KIND} is absent, the return value is of default integer kind.
14735If @var{DIM} is absent, the result is an array of the lower cobounds of
14736@var{COARRAY}.  If @var{DIM} is present, the result is a scalar
14737corresponding to the lower cobound of the array along that codimension.
14738
14739@item @emph{See also}:
14740@ref{LCOBOUND}, @gol
14741@ref{LBOUND}
14742@end table
14743
14744
14745
14746@node UMASK
14747@section @code{UMASK} --- Set the file creation mask
14748@fnindex UMASK
14749@cindex file system, file creation mask
14750
14751@table @asis
14752@item @emph{Description}:
14753Sets the file creation mask to @var{MASK}. If called as a function, it
14754returns the old value. If called as a subroutine and argument @var{OLD}
14755if it is supplied, it is set to the old value. See @code{umask(2)}.
14756
14757@item @emph{Standard}:
14758GNU extension
14759
14760@item @emph{Class}:
14761Subroutine, function
14762
14763@item @emph{Syntax}:
14764@multitable @columnfractions .80
14765@item @code{CALL UMASK(MASK [, OLD])}
14766@item @code{OLD = UMASK(MASK)}
14767@end multitable
14768
14769@item @emph{Arguments}:
14770@multitable @columnfractions .15 .70
14771@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14772@item @var{OLD} @tab (Optional) Shall be a scalar of type
14773@code{INTEGER}.
14774@end multitable
14775
14776@end table
14777
14778
14779
14780@node UNLINK
14781@section @code{UNLINK} --- Remove a file from the file system
14782@fnindex UNLINK
14783@cindex file system, remove file
14784
14785@table @asis
14786@item @emph{Description}:
14787Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14788used to mark the end of the name in @var{PATH}; otherwise, trailing
14789blanks in the file name are ignored.  If the @var{STATUS} argument is
14790supplied, it contains 0 on success or a nonzero error code upon return;
14791see @code{unlink(2)}.
14792
14793This intrinsic is provided in both subroutine and function forms;
14794however, only one form can be used in any given program unit.
14795
14796@item @emph{Standard}:
14797GNU extension
14798
14799@item @emph{Class}:
14800Subroutine, function
14801
14802@item @emph{Syntax}:
14803@multitable @columnfractions .80
14804@item @code{CALL UNLINK(PATH [, STATUS])}
14805@item @code{STATUS = UNLINK(PATH)}
14806@end multitable
14807
14808@item @emph{Arguments}:
14809@multitable @columnfractions .15 .70
14810@item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14811@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14812@end multitable
14813
14814@item @emph{See also}:
14815@ref{LINK}, @gol
14816@ref{SYMLNK}
14817@end table
14818
14819
14820
14821@node UNPACK
14822@section @code{UNPACK} --- Unpack an array of rank one into an array
14823@fnindex UNPACK
14824@cindex array, unpacking
14825@cindex array, increase dimension
14826@cindex array, scatter elements
14827
14828@table @asis
14829@item @emph{Description}:
14830Store the elements of @var{VECTOR} in an array of higher rank.
14831
14832@item @emph{Standard}:
14833Fortran 90 and later
14834
14835@item @emph{Class}:
14836Transformational function
14837
14838@item @emph{Syntax}:
14839@code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14840
14841@item @emph{Arguments}:
14842@multitable @columnfractions .15 .70
14843@item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14844shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14845@item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
14846@item @var{FIELD}  @tab Shall be of the same type as @var{VECTOR} and have
14847the same shape as @var{MASK}.
14848@end multitable
14849
14850@item @emph{Return value}:
14851The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14852of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14853
14854@item @emph{Example}:
14855@smallexample
14856PROGRAM test_unpack
14857  integer :: vector(2)  = (/1,1/)
14858  logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14859  integer :: field(2,2) = 0, unity(2,2)
14860
14861  ! result: unity matrix
14862  unity = unpack(vector, reshape(mask, (/2,2/)), field)
14863END PROGRAM
14864@end smallexample
14865
14866@item @emph{See also}:
14867@ref{PACK}, @gol
14868@ref{SPREAD}
14869@end table
14870
14871
14872
14873@node VERIFY
14874@section @code{VERIFY} --- Scan a string for characters not a given set
14875@fnindex VERIFY
14876@cindex string, find missing set
14877
14878@table @asis
14879@item @emph{Description}:
14880Verifies that all the characters in @var{STRING} belong to the set of
14881characters in @var{SET}.
14882
14883If @var{BACK} is either absent or equals @code{FALSE}, this function
14884returns the position of the leftmost character of @var{STRING} that is
14885not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14886position is returned. If all characters of @var{STRING} are found in
14887@var{SET}, the result is zero.
14888
14889@item @emph{Standard}:
14890Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14891
14892@item @emph{Class}:
14893Elemental function
14894
14895@item @emph{Syntax}:
14896@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14897
14898@item @emph{Arguments}:
14899@multitable @columnfractions .15 .70
14900@item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14901@item @var{SET}    @tab Shall be of type @code{CHARACTER}.
14902@item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
14903@item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
14904expression indicating the kind parameter of the result.
14905@end multitable
14906
14907@item @emph{Return value}:
14908The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14909@var{KIND} is absent, the return value is of default integer kind.
14910
14911@item @emph{Example}:
14912@smallexample
14913PROGRAM test_verify
14914  WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
14915  WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
14916  WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
14917  WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
14918  WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
14919END PROGRAM
14920@end smallexample
14921
14922@item @emph{See also}:
14923@ref{SCAN}, @gol
14924@ref{INDEX intrinsic}
14925@end table
14926
14927
14928
14929@node XOR
14930@section @code{XOR} --- Bitwise logical exclusive OR
14931@fnindex XOR
14932@cindex bitwise logical exclusive or
14933@cindex logical exclusive or, bitwise
14934
14935@table @asis
14936@item @emph{Description}:
14937Bitwise logical exclusive or.
14938
14939This intrinsic routine is provided for backwards compatibility with
14940GNU Fortran 77.  For integer arguments, programmers should consider
14941the use of the @ref{IEOR} intrinsic and for logical arguments the
14942@code{.NEQV.} operator, which are both defined by the Fortran standard.
14943
14944@item @emph{Standard}:
14945GNU extension
14946
14947@item @emph{Class}:
14948Function
14949
14950@item @emph{Syntax}:
14951@code{RESULT = XOR(I, J)}
14952
14953@item @emph{Arguments}:
14954@multitable @columnfractions .15 .70
14955@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
14956type or a scalar @code{LOGICAL} type or a boz-literal-constant.
14957@item @var{J} @tab The type shall be the same as the type of @var{I} or
14958a boz-literal-constant. @var{I} and @var{J} shall not both be
14959boz-literal-constants.  If either @var{I} and @var{J} is a
14960boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
14961@end multitable
14962
14963@item @emph{Return value}:
14964The return type is either a scalar @code{INTEGER} or a scalar
14965@code{LOGICAL}.  If the kind type parameters differ, then the
14966smaller kind type is implicitly converted to larger kind, and the
14967return has the larger kind.  A boz-literal-constant is
14968converted to an @code{INTEGER} with the kind type parameter of
14969the other argument as-if a call to @ref{INT} occurred.
14970
14971@item @emph{Example}:
14972@smallexample
14973PROGRAM test_xor
14974  LOGICAL :: T = .TRUE., F = .FALSE.
14975  INTEGER :: a, b
14976  DATA a / Z'F' /, b / Z'3' /
14977
14978  WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
14979  WRITE (*,*) XOR(a, b)
14980END PROGRAM
14981@end smallexample
14982
14983@item @emph{See also}:
14984Fortran 95 elemental function: @gol
14985@ref{IEOR}
14986@end table
14987
14988
14989
14990@node Intrinsic Modules
14991@chapter Intrinsic Modules
14992@cindex intrinsic Modules
14993
14994@menu
14995* ISO_FORTRAN_ENV::
14996* ISO_C_BINDING::
14997* IEEE modules::
14998* OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
14999* OpenACC Module OPENACC::
15000@end menu
15001
15002@node ISO_FORTRAN_ENV
15003@section @code{ISO_FORTRAN_ENV}
15004@table @asis
15005@item @emph{Standard}:
15006Fortran 2003 and later, except when otherwise noted
15007@end table
15008
15009The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
15010named constants:
15011
15012@table @asis
15013@item @code{ATOMIC_INT_KIND}:
15014Default-kind integer constant to be used as kind parameter when defining
15015integer variables used in atomic operations. (Fortran 2008 or later.)
15016
15017@item @code{ATOMIC_LOGICAL_KIND}:
15018Default-kind integer constant to be used as kind parameter when defining
15019logical variables used in atomic operations. (Fortran 2008 or later.)
15020
15021@item @code{CHARACTER_KINDS}:
15022Default-kind integer constant array of rank one containing the supported kind
15023parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
15024
15025@item @code{CHARACTER_STORAGE_SIZE}:
15026Size in bits of the character storage unit.
15027
15028@item @code{ERROR_UNIT}:
15029Identifies the preconnected unit used for error reporting.
15030
15031@item @code{FILE_STORAGE_SIZE}:
15032Size in bits of the file-storage unit.
15033
15034@item @code{INPUT_UNIT}:
15035Identifies the preconnected unit identified by the asterisk
15036(@code{*}) in @code{READ} statement.
15037
15038@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
15039Kind type parameters to specify an INTEGER type with a storage
15040size of 16, 32, and 64 bits. It is negative if a target platform
15041does not support the particular kind. (Fortran 2008 or later.)
15042
15043@item @code{INTEGER_KINDS}:
15044Default-kind integer constant array of rank one containing the supported kind
15045parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
15046
15047@item @code{IOSTAT_END}:
15048The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15049an input/output statement if an end-of-file condition occurred.
15050
15051@item @code{IOSTAT_EOR}:
15052The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15053an input/output statement if an end-of-record condition occurred.
15054
15055@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
15056Scalar default-integer constant, used by @code{INQUIRE} for the
15057@code{IOSTAT=} specifier to denote an that a unit number identifies an
15058internal unit. (Fortran 2008 or later.)
15059
15060@item @code{NUMERIC_STORAGE_SIZE}:
15061The size in bits of the numeric storage unit.
15062
15063@item @code{LOGICAL_KINDS}:
15064Default-kind integer constant array of rank one containing the supported kind
15065parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
15066
15067@item @code{OUTPUT_UNIT}:
15068Identifies the preconnected unit identified by the asterisk
15069(@code{*}) in @code{WRITE} statement.
15070
15071@item @code{REAL32}, @code{REAL64}, @code{REAL128}:
15072Kind type parameters to specify a REAL type with a storage
15073size of 32, 64, and 128 bits. It is negative if a target platform
15074does not support the particular kind. (Fortran 2008 or later.)
15075
15076@item @code{REAL_KINDS}:
15077Default-kind integer constant array of rank one containing the supported kind
15078parameters of the @code{REAL} type. (Fortran 2008 or later.)
15079
15080@item @code{STAT_LOCKED}:
15081Scalar default-integer constant used as STAT= return value by @code{LOCK} to
15082denote that the lock variable is locked by the executing image. (Fortran 2008
15083or later.)
15084
15085@item @code{STAT_LOCKED_OTHER_IMAGE}:
15086Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15087denote that the lock variable is locked by another image. (Fortran 2008 or
15088later.)
15089
15090@item @code{STAT_STOPPED_IMAGE}:
15091Positive, scalar default-integer constant used as STAT= return value if the
15092argument in the statement requires synchronisation with an image, which has
15093initiated the termination of the execution. (Fortran 2008 or later.)
15094
15095@item @code{STAT_FAILED_IMAGE}:
15096Positive, scalar default-integer constant used as STAT= return value if the
15097argument in the statement requires communication with an image, which has
15098is in the failed state. (TS 18508 or later.)
15099
15100@item @code{STAT_UNLOCKED}:
15101Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15102denote that the lock variable is unlocked. (Fortran 2008 or later.)
15103@end table
15104
15105The module provides the following derived type:
15106
15107@table @asis
15108@item @code{LOCK_TYPE}:
15109Derived type with private components to be use with the @code{LOCK} and
15110@code{UNLOCK} statement. A variable of its type has to be always declared
15111as coarray and may not appear in a variable-definition context.
15112(Fortran 2008 or later.)
15113@end table
15114
15115The module also provides the following intrinsic procedures:
15116@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
15117
15118
15119
15120@node ISO_C_BINDING
15121@section @code{ISO_C_BINDING}
15122@table @asis
15123@item @emph{Standard}:
15124Fortran 2003 and later, GNU extensions
15125@end table
15126
15127The following intrinsic procedures are provided by the module; their
15128definition can be found in the section Intrinsic Procedures of this
15129manual.
15130
15131@table @asis
15132@item @code{C_ASSOCIATED}
15133@item @code{C_F_POINTER}
15134@item @code{C_F_PROCPOINTER}
15135@item @code{C_FUNLOC}
15136@item @code{C_LOC}
15137@item @code{C_SIZEOF}
15138@end table
15139@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
15140@c don't really know why.
15141
15142The @code{ISO_C_BINDING} module provides the following named constants of
15143type default integer, which can be used as KIND type parameters.
15144
15145In addition to the integer named constants required by the Fortran 2003
15146standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
15147extension named constants for the 128-bit integer types supported by the
15148C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
15149Furthermore, if @code{_Float128} is supported in C, the named constants
15150@code{C_FLOAT128} and @code{C_FLOAT128_COMPLEX} are defined.
15151
15152@multitable @columnfractions .19 .32 .34 .15
15153@headitem Fortran Type  @tab Named constant         @tab C type                                @tab Extension
15154@item @code{INTEGER}@tab @code{C_INT}           @tab @code{int}
15155@item @code{INTEGER}@tab @code{C_SHORT}         @tab @code{short int}
15156@item @code{INTEGER}@tab @code{C_LONG}          @tab @code{long int}
15157@item @code{INTEGER}@tab @code{C_LONG_LONG}     @tab @code{long long int}
15158@item @code{INTEGER}@tab @code{C_SIGNED_CHAR}   @tab @code{signed char}/@code{unsigned char}
15159@item @code{INTEGER}@tab @code{C_SIZE_T}        @tab @code{size_t}
15160@item @code{INTEGER}@tab @code{C_INT8_T}        @tab @code{int8_t}
15161@item @code{INTEGER}@tab @code{C_INT16_T}       @tab @code{int16_t}
15162@item @code{INTEGER}@tab @code{C_INT32_T}       @tab @code{int32_t}
15163@item @code{INTEGER}@tab @code{C_INT64_T}       @tab @code{int64_t}
15164@item @code{INTEGER}@tab @code{C_INT128_T}      @tab @code{int128_t}                      @tab Ext.
15165@item @code{INTEGER}@tab @code{C_INT_LEAST8_T}  @tab @code{int_least8_t}
15166@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
15167@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
15168@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
15169@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t}                @tab Ext.
15170@item @code{INTEGER}@tab @code{C_INT_FAST8_T}   @tab @code{int_fast8_t}
15171@item @code{INTEGER}@tab @code{C_INT_FAST16_T}  @tab @code{int_fast16_t}
15172@item @code{INTEGER}@tab @code{C_INT_FAST32_T}  @tab @code{int_fast32_t}
15173@item @code{INTEGER}@tab @code{C_INT_FAST64_T}  @tab @code{int_fast64_t}
15174@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t}                 @tab Ext.
15175@item @code{INTEGER}@tab @code{C_INTMAX_T}      @tab @code{intmax_t}
15176@item @code{INTEGER}@tab @code{C_INTPTR_T}      @tab @code{intptr_t}
15177@item @code{INTEGER}@tab @code{C_PTRDIFF_T}     @tab @code{ptrdiff_t}                     @tab TS 29113
15178@item @code{REAL}   @tab @code{C_FLOAT}         @tab @code{float}
15179@item @code{REAL}   @tab @code{C_DOUBLE}        @tab @code{double}
15180@item @code{REAL}   @tab @code{C_LONG_DOUBLE}   @tab @code{long double}
15181@item @code{REAL}   @tab @code{C_FLOAT128}      @tab @code{_Float128}                    @tab Ext.
15182@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
15183@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
15184@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
15185@item @code{COMPLEX}@tab @code{C_FLOAT128_COMPLEX}   @tab @code{_Float128 _Complex}      @tab Ext.
15186@item @code{LOGICAL}@tab @code{C_BOOL}          @tab @code{_Bool}
15187@item @code{CHARACTER}@tab @code{C_CHAR}        @tab @code{char}
15188@end multitable
15189
15190Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
15191are defined.
15192
15193@multitable @columnfractions .20 .45 .15
15194@headitem Name                     @tab C definition    @tab Value
15195@item @code{C_NULL_CHAR}       @tab null character  @tab @code{'\0'}
15196@item @code{C_ALERT}           @tab alert           @tab @code{'\a'}
15197@item @code{C_BACKSPACE}       @tab backspace       @tab @code{'\b'}
15198@item @code{C_FORM_FEED}       @tab form feed       @tab @code{'\f'}
15199@item @code{C_NEW_LINE}        @tab new line        @tab @code{'\n'}
15200@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
15201@item @code{C_HORIZONTAL_TAB}  @tab horizontal tab  @tab @code{'\t'}
15202@item @code{C_VERTICAL_TAB}    @tab vertical tab    @tab @code{'\v'}
15203@end multitable
15204
15205Moreover, the following two named constants are defined:
15206
15207@multitable @columnfractions .20 .80
15208@headitem Name                 @tab Type
15209@item @code{C_NULL_PTR}    @tab @code{C_PTR}
15210@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
15211@end multitable
15212
15213Both are equivalent to the value @code{NULL} in C.
15214
15215
15216
15217@node IEEE modules
15218@section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15219@table @asis
15220@item @emph{Standard}:
15221Fortran 2003 and later
15222@end table
15223
15224The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15225intrinsic modules provide support for exceptions and IEEE arithmetic, as
15226defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
15227(@emph{Binary floating-point arithmetic for microprocessor systems}). These
15228modules are only provided on the following supported platforms:
15229
15230@itemize @bullet
15231@item i386 and x86_64 processors
15232@item platforms which use the GNU C Library (glibc)
15233@item platforms with support for SysV/386 routines for floating point
15234interface (including Solaris and BSDs)
15235@item platforms with the AIX OS
15236@end itemize
15237
15238For full compliance with the Fortran standards, code using the
15239@code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
15240with the following options: @code{-fno-unsafe-math-optimizations
15241-frounding-math -fsignaling-nans}.
15242
15243
15244
15245@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
15246@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
15247@table @asis
15248@item @emph{Standard}:
15249OpenMP Application Program Interface v4.5,
15250OpenMP Application Program Interface v5.0 (partially supported) and
15251OpenMP Application Program Interface v5.1 (partially supported).
15252@end table
15253
15254The OpenMP Fortran runtime library routines are provided both in
15255a form of two Fortran modules, named @code{OMP_LIB} and
15256@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
15257@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
15258in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
15259Processing Runtime Library} manual,
15260the named constants defined in the modules are listed
15261below.
15262
15263For details refer to the actual
15264@uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
15265OpenMP Application Program Interface v4.5} and
15266@uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5.0.pdf,
15267OpenMP Application Program Interface v5.0}.
15268
15269@code{OMP_LIB_KINDS} provides the following scalar default-integer
15270named constants:
15271
15272@table @asis
15273@item @code{omp_allocator_handle_kind}
15274@item @code{omp_alloctrait_key_kind}
15275@item @code{omp_alloctrait_val_kind}
15276@item @code{omp_depend_kind}
15277@item @code{omp_lock_kind}
15278@item @code{omp_lock_hint_kind}
15279@item @code{omp_nest_lock_kind}
15280@item @code{omp_pause_resource_kind}
15281@item @code{omp_memspace_handle_kind}
15282@item @code{omp_proc_bind_kind}
15283@item @code{omp_sched_kind}
15284@item @code{omp_sync_hint_kind}
15285@end table
15286
15287@code{OMP_LIB} provides the scalar default-integer
15288named constant @code{openmp_version} with a value of the form
15289@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15290of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
15291
15292The following derived type:
15293
15294@table @asis
15295@item @code{omp_alloctrait}
15296@end table
15297
15298The following scalar integer named constants of the
15299kind @code{omp_sched_kind}:
15300
15301@table @asis
15302@item @code{omp_sched_static}
15303@item @code{omp_sched_dynamic}
15304@item @code{omp_sched_guided}
15305@item @code{omp_sched_auto}
15306@end table
15307
15308And the following scalar integer named constants of the
15309kind @code{omp_proc_bind_kind}:
15310
15311@table @asis
15312@item @code{omp_proc_bind_false}
15313@item @code{omp_proc_bind_true}
15314@item @code{omp_proc_bind_primary}
15315@item @code{omp_proc_bind_master}
15316@item @code{omp_proc_bind_close}
15317@item @code{omp_proc_bind_spread}
15318@end table
15319
15320The following scalar integer named constants are of the
15321kind @code{omp_lock_hint_kind}:
15322
15323@table @asis
15324@item @code{omp_lock_hint_none}
15325@item @code{omp_lock_hint_uncontended}
15326@item @code{omp_lock_hint_contended}
15327@item @code{omp_lock_hint_nonspeculative}
15328@item @code{omp_lock_hint_speculative}
15329@item @code{omp_sync_hint_none}
15330@item @code{omp_sync_hint_uncontended}
15331@item @code{omp_sync_hint_contended}
15332@item @code{omp_sync_hint_nonspeculative}
15333@item @code{omp_sync_hint_speculative}
15334@end table
15335
15336And the following two scalar integer named constants are of the
15337kind @code{omp_pause_resource_kind}:
15338
15339@table @asis
15340@item @code{omp_pause_soft}
15341@item @code{omp_pause_hard}
15342@end table
15343
15344The following scalar integer named constants are of the kind
15345@code{omp_alloctrait_key_kind}:
15346
15347@table @asis
15348@item @code{omp_atk_sync_hint}
15349@item @code{omp_atk_alignment}
15350@item @code{omp_atk_access}
15351@item @code{omp_atk_pool_size}
15352@item @code{omp_atk_fallback}
15353@item @code{omp_atk_fb_data}
15354@item @code{omp_atk_pinned}
15355@item @code{omp_atk_partition}
15356@end table
15357
15358The following scalar integer named constants are of the kind
15359@code{omp_alloctrait_val_kind}:
15360
15361@table @asis
15362@code{omp_alloctrait_key_kind}:
15363@item @code{omp_atv_default}
15364@item @code{omp_atv_false}
15365@item @code{omp_atv_true}
15366@item @code{omp_atv_contended}
15367@item @code{omp_atv_uncontended}
15368@item @code{omp_atv_serialized}
15369@item @code{omp_atv_sequential}
15370@item @code{omp_atv_private}
15371@item @code{omp_atv_all}
15372@item @code{omp_atv_thread}
15373@item @code{omp_atv_pteam}
15374@item @code{omp_atv_cgroup}
15375@item @code{omp_atv_default_mem_fb}
15376@item @code{omp_atv_null_fb}
15377@item @code{omp_atv_abort_fb}
15378@item @code{omp_atv_allocator_fb}
15379@item @code{omp_atv_environment}
15380@item @code{omp_atv_nearest}
15381@item @code{omp_atv_blocked}
15382@end table
15383
15384The following scalar integer named constants are of the kind
15385@code{omp_allocator_handle_kind}:
15386
15387@table @asis
15388@item @code{omp_null_allocator}
15389@item @code{omp_default_mem_alloc}
15390@item @code{omp_large_cap_mem_alloc}
15391@item @code{omp_const_mem_alloc}
15392@item @code{omp_high_bw_mem_alloc}
15393@item @code{omp_low_lat_mem_alloc}
15394@item @code{omp_cgroup_mem_alloc}
15395@item @code{omp_pteam_mem_alloc}
15396@item @code{omp_thread_mem_alloc}
15397@end table
15398
15399The following scalar integer named constants are of the kind
15400@code{omp_memspace_handle_kind}:
15401
15402@table @asis
15403@item @code{omp_default_mem_space}
15404@item @code{omp_large_cap_mem_space}
15405@item @code{omp_const_mem_space}
15406@item @code{omp_high_bw_mem_space}
15407@item @code{omp_low_lat_mem_space}
15408@end table
15409
15410
15411
15412@node OpenACC Module OPENACC
15413@section OpenACC Module @code{OPENACC}
15414@table @asis
15415@item @emph{Standard}:
15416OpenACC Application Programming Interface v2.6
15417@end table
15418
15419
15420The OpenACC Fortran runtime library routines are provided both in a
15421form of a Fortran 90 module, named @code{OPENACC}, and in form of a
15422Fortran @code{include} file named @file{openacc_lib.h}.  The
15423procedures provided by @code{OPENACC} can be found in the
15424@ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
15425Runtime Library} manual, the named constants defined in the modules
15426are listed below.
15427
15428For details refer to the actual
15429@uref{http://www.openacc.org/,
15430OpenACC Application Programming Interface v2.6}.
15431
15432@code{OPENACC} provides the scalar default-integer
15433named constant @code{openacc_version} with a value of the form
15434@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15435of the OpenACC version; for OpenACC v2.6 the value is @code{201711}.
15436