intrinsic.texi

理解和实践操作系统的一本好书

@ignore
Copyright (C) 2005, 2006, 2007
Free Software Foundation, Inc.
This is part of the GNU Fortran manual.   
For copying conditions, see the file gfortran.texi.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'' and ``Funding
Free Software'', the Front-Cover texts being (a) (see below), and with
the Back-Cover Texts being (b) (see below).  A copy of the license is
included in the gfdl(7) man page.


Some basic guidelines for editing this document:

  (1) The intrinsic procedures are to be listed in alphabetical order.
  (2) The generic name is to be used.
  (3) The specific names are included in the function index and in a
      table at the end of the node (See ABS entry).
  (4) Try to maintain the same style for each entry.


@end ignore

@tex
\gdef\acos{\mathop{\rm acos}\nolimits}
\gdef\asin{\mathop{\rm asin}\nolimits}
\gdef\atan{\mathop{\rm atan}\nolimits}
\gdef\acosh{\mathop{\rm acosh}\nolimits}
\gdef\asinh{\mathop{\rm asinh}\nolimits}
\gdef\atanh{\mathop{\rm atanh}\nolimits}
@end tex


@node Intrinsic Procedures
@chapter Intrinsic Procedures
@cindex intrinsic procedures

@menu
* Introduction:         Introduction to Intrinsics
* @code{ABORT}:         ABORT,     Abort the program     
* @code{ABS}:           ABS,       Absolute value     
* @code{ACCESS}:        ACCESS,    Checks file access modes
* @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
* @code{ACOS}:          ACOS,      Arccosine function
* @code{ACOSH}:         ACOSH,     Hyperbolic arccosine function
* @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
* @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
* @code{AIMAG}:         AIMAG,     Imaginary part of complex number
* @code{AINT}:          AINT,      Truncate to a whole number
* @code{ALARM}:         ALARM,     Set an alarm clock
* @code{ALL}:           ALL,       Determine if all values are true
* @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
* @code{AND}:           AND,       Bitwise logical AND
* @code{ANINT}:         ANINT,     Nearest whole number
* @code{ANY}:           ANY,       Determine if any values are true
* @code{ASIN}:          ASIN,      Arcsine function
* @code{ASINH}:         ASINH,     Hyperbolic arcsine function
* @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
* @code{ATAN}:          ATAN,      Arctangent function
* @code{ATAN2}:         ATAN2,     Arctangent function
* @code{ATANH}:         ATANH,     Hyperbolic arctangent function
* @code{BESJ0}:         BESJ0,     Bessel function of the first kind of order 0
* @code{BESJ1}:         BESJ1,     Bessel function of the first kind of order 1
* @code{BESJN}:         BESJN,     Bessel function of the first kind
* @code{BESY0}:         BESY0,     Bessel function of the second kind of order 0
* @code{BESY1}:         BESY1,     Bessel function of the second kind of order 1
* @code{BESYN}:         BESYN,     Bessel function of the second kind
* @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
* @code{BTEST}:         BTEST,     Bit test function
* @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
* @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
* @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
* @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
* @code{C_LOC}:         C_LOC,     Obtain the C address of an object
* @code{CEILING}:       CEILING,   Integer ceiling function
* @code{CHAR}:          CHAR,      Integer-to-character conversion function
* @code{CHDIR}:         CHDIR,     Change working directory
* @code{CHMOD}:         CHMOD,     Change access permissions of files
* @code{CMPLX}:         CMPLX,     Complex conversion function
* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
* @code{COMPLEX}:       COMPLEX,   Complex conversion function
* @code{CONJG}:         CONJG,     Complex conjugate function
* @code{COS}:           COS,       Cosine function
* @code{COSH}:          COSH,      Hyperbolic cosine function
* @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
* @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
* @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
* @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
* @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
* @code{DBLE}:          DBLE,      Double precision conversion function
* @code{DCMPLX}:        DCMPLX,    Double complex conversion function
* @code{DFLOAT}:        DFLOAT,    Double precision conversion function
* @code{DIGITS}:        DIGITS,    Significant digits function
* @code{DIM}:           DIM,       Positive difference
* @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
* @code{DPROD}:         DPROD,     Double product function
* @code{DREAL}:         DREAL,     Double real part function
* @code{DTIME}:         DTIME,     Execution time subroutine (or function)
* @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
* @code{EPSILON}:       EPSILON,   Epsilon function
* @code{ERF}:           ERF,       Error function
* @code{ERFC}:          ERFC,      Complementary error function
* @code{ETIME}:         ETIME,     Execution time subroutine (or function)
* @code{EXIT}:          EXIT,      Exit the program with status.
* @code{EXP}:           EXP,       Exponential function
* @code{EXPONENT}:      EXPONENT,  Exponent function
* @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
* @code{FGET}:          FGET,      Read a single character in stream mode from stdin
* @code{FGETC}:         FGETC,     Read a single character in stream mode
* @code{FLOAT}:         FLOAT,     Convert integer to default real
* @code{FLOOR}:         FLOOR,     Integer floor function
* @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
* @code{FNUM}:          FNUM,      File number function
* @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
* @code{FPUTC}:         FPUTC,     Write a single character in stream mode
* @code{FRACTION}:      FRACTION,  Fractional part of the model representation
* @code{FREE}:          FREE,      Memory de-allocation subroutine
* @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
* @code{FSTAT}:         FSTAT,     Get file status
* @code{FTELL}:         FTELL,     Current stream position
* @code{GAMMA}:         GAMMA,     Gamma function
* @code{GERROR}:        GERROR,    Get last system error message
* @code{GETARG}:        GETARG,    Get command line arguments
* @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
* @code{GETCWD}:        GETCWD,    Get current working directory
* @code{GETENV}:        GETENV,    Get an environmental variable
* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
* @code{GETGID}:        GETGID,    Group ID function
* @code{GETLOG}:        GETLOG,    Get login name
* @code{GETPID}:        GETPID,    Process ID function
* @code{GETUID}:        GETUID,    User ID function
* @code{GMTIME}:        GMTIME,    Convert time to GMT info
* @code{HOSTNM}:        HOSTNM,    Get system host name
* @code{HUGE}:          HUGE,      Largest number of a kind
* @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
* @code{IAND}:          IAND,      Bitwise logical and
* @code{IARGC}:         IARGC,     Get the number of command line arguments
* @code{IBCLR}:         IBCLR,     Clear bit
* @code{IBITS}:         IBITS,     Bit extraction
* @code{IBSET}:         IBSET,     Set bit
* @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
* @code{IDATE}:         IDATE,     Current local time (day/month/year)
* @code{IEOR}:          IEOR,      Bitwise logical exclusive or
* @code{IERRNO}:        IERRNO,    Function to get the last system error number
* @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
* @code{INT}:           INT,       Convert to integer type
* @code{INT2}:          INT2,      Convert to 16-bit integer type
* @code{INT8}:          INT8,      Convert to 64-bit integer type
* @code{IOR}:           IOR,       Bitwise logical or
* @code{IRAND}:         IRAND,     Integer pseudo-random number
* @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
* @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
* @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
* @code{ISHFT}:         ISHFT,     Shift bits
* @code{ISHFTC}:        ISHFTC,    Shift bits circularly
* @code{ISNAN}:         ISNAN,     Tests for a NaN
* @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
* @code{KILL}:          KILL,      Send a signal to a process
* @code{KIND}:          KIND,      Kind of an entity
* @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
* @code{LEN}:           LEN,       Length of a character entity
* @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
* @code{LGAMMA}:        LGAMMA,    Logarithm of the Gamma function
* @code{LGE}:           LGE,       Lexical greater than or equal
* @code{LGT}:           LGT,       Lexical greater than
* @code{LINK}:          LINK,      Create a hard link
* @code{LLE}:           LLE,       Lexical less than or equal
* @code{LLT}:           LLT,       Lexical less than
* @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
* @code{LOC}:           LOC,       Returns the address of a variable
* @code{LOG}:           LOG,       Logarithm function
* @code{LOG10}:         LOG10,     Base 10 logarithm function 
* @code{LOGICAL}:       LOGICAL,   Convert to logical type
* @code{LONG}:          LONG,      Convert to integer type
* @code{LSHIFT}:        LSHIFT,    Left shift bits
* @code{LSTAT}:         LSTAT,     Get file status
* @code{LTIME}:         LTIME,     Convert time to local time info
* @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
* @code{MATMUL}:        MATMUL,    matrix multiplication
* @code{MAX}:           MAX,       Maximum value of an argument list
* @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
* @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
* @code{MAXVAL}:        MAXVAL,    Maximum value of an array
* @code{MCLOCK}:        MCLOCK,    Time function
* @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
* @code{MERGE}:         MERGE,     Merge arrays
* @code{MIN}:           MIN,       Minimum value of an argument list
* @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
* @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
* @code{MINVAL}:        MINVAL,    Minimum value of an array
* @code{MOD}:           MOD,       Remainder function
* @code{MODULO}:        MODULO,    Modulo function
* @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
* @code{MVBITS}:        MVBITS,    Move bits from one integer to another
* @code{NEAREST}:       NEAREST,   Nearest representable number
* @code{NEW_LINE}:      NEW_LINE,  New line character
* @code{NINT}:          NINT,      Nearest whole number
* @code{NOT}:           NOT,       Logical negation
* @code{NULL}:          NULL,      Function that returns an disassociated pointer
* @code{OR}:            OR,        Bitwise logical OR
* @code{PACK}:          PACK,      Pack an array into an array of rank one
* @code{PERROR}:        PERROR,    Print system error message
* @code{PRECISION}:     PRECISION, Decimal precision of a real kind
* @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
* @code{PRODUCT}:       PRODUCT,   Product of array elements
* @code{RADIX}:         RADIX,     Base of a data model
* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
* @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
* @code{RAND}:          RAND,      Real pseudo-random number
* @code{RANGE}:         RANGE,     Decimal exponent range of a real kind
* @code{RAN}:           RAN,       Real pseudo-random number
* @code{REAL}:          REAL,      Convert to real type 
* @code{RENAME}:        RENAME,    Rename a file
* @code{REPEAT}:        REPEAT,    Repeated string concatenation
* @code{RESHAPE}:       RESHAPE,   Function to reshape an array
* @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
* @code{RSHIFT}:        RSHIFT,    Right shift bits
* @code{SCALE}:         SCALE,     Scale a real value
* @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
* @code{SECNDS}:        SECNDS,    Time function
* @code{SECOND}:        SECOND,    CPU time function
* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
* @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
* @code{SHAPE}:         SHAPE,     Determine the shape of an array
* @code{SIGN}:          SIGN,      Sign copying function
* @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
* @code{SIN}:           SIN,       Sine function
* @code{SINH}:          SINH,      Hyperbolic sine function
* @code{SIZE}:          SIZE,      Function to determine the size of an array
* @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
* @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
* @code{SNGL}:          SNGL,      Convert double precision real to default real
* @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
* @code{SPREAD}:        SPREAD,    Add a dimension to an array 
* @code{SQRT}:          SQRT,      Square-root function
* @code{SRAND}:         SRAND,     Reinitialize the random number generator
* @code{STAT}:          STAT,      Get file status
* @code{SUM}:           SUM,       Sum of array elements
* @code{SYMLNK}:        SYMLNK,    Create a symbolic link
* @code{SYSTEM}:        SYSTEM,    Execute a shell command
* @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
* @code{TAN}:           TAN,       Tangent function
* @code{TANH}:          TANH,      Hyperbolic tangent function
* @code{TIME}:          TIME,      Time function
* @code{TIME8}:         TIME8,     Time function (64-bit)
* @code{TINY}:          TINY,      Smallest positive number of a real kind
* @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
* @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
* @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
* @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
* @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
* @code{UMASK}:         UMASK,     Set the file creation mask
* @code{UNLINK}:        UNLINK,    Remove a file from the file system
* @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
* @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
* @code{XOR}:           XOR,       Bitwise logical exclusive or
@end menu

@node Introduction to Intrinsics
@section Introduction to intrinsic procedures

The intrinsic procedures provided by GNU Fortran include all of the
intrinsic procedures required by the Fortran 95 standard, a set of
intrinsic procedures for backwards compatibility with G77, and a small
selection of intrinsic procedures from the Fortran 2003 standard.  Any
conflict between a description here and a description in either the
Fortran 95 standard or the Fortran 2003 standard is unintentional, and
the standard(s) should be considered authoritative.

The enumeration of the @code{KIND} type parameter is processor defined in
the Fortran 95 standard.  GNU Fortran defines the default integer type and
default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
respectively.  The standard mandates that both data types shall have
another kind, which have more precision.  On typical target architectures
supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
In the description of generic intrinsic procedures, the kind type parameter
will be specified by @code{KIND=*}, and in the description of specific
names for an intrinsic procedure the kind type parameter will be explicitly
given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
brevity the optional @code{KIND=} syntax will be omitted.

Many of the intrinsic procedures take one or more optional arguments.
This document follows the convention used in the Fortran 95 standard,
and denotes such arguments by square brackets.

GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
which can be used to restrict the set of intrinsic procedures to a 
given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
option, and so all intrinsic procedures described here are accepted.  There
is one caveat.  For a select group of intrinsic procedures, @command{g77}
implemented both a function and a subroutine.  Both classes 
have been implemented in @command{gfortran} for backwards compatibility
with @command{g77}.  It is noted here that these functions and subroutines
cannot be intermixed in a given subprogram.  In the descriptions that follow,
the applicable standard for each intrinsic procedure is noted.



@node ABORT
@section @code{ABORT} --- Abort the program
@fnindex ABORT
@cindex program termination, with core dump
@cindex terminate program, with core dump
@cindex core, dump

@table @asis
@item @emph{Description}:
@code{ABORT} causes immediate termination of the program.  On operating
systems that support a core dump, @code{ABORT} will produce a core dump,
which is suitable for debugging purposes.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL ABORT}

@item @emph{Return value}:
Does not return.

@item @emph{Example}:
@smallexample
program test_abort
  integer :: i = 1, j = 2
  if (i /= j) call abort
end program test_abort
@end smallexample

@item @emph{See also}:
@ref{EXIT}, @ref{KILL}

@end table



@node ABS
@section @code{ABS} --- Absolute value
@fnindex ABS
@fnindex CABS
@fnindex DABS
@fnindex IABS
@fnindex ZABS
@fnindex CDABS
@cindex absolute value

@table @asis
@item @emph{Description}:
@code{ABS(X)} computes the absolute value of @code{X}.

@item @emph{Standard}:
F77 and later, has overloads that are GNU extensions

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ABS(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
@code{REAL(*)}, or @code{COMPLEX(*)}.
@end multitable

@item @emph{Return value}:
The return value is of the same type and
kind as the argument except the return value is @code{REAL(*)} for a
@code{COMPLEX(*)} argument.

@item @emph{Example}:
@smallexample
program test_abs
  integer :: i = -1
  real :: x = -1.e0
  complex :: z = (-1.e0,0.e0)
  i = abs(i)
  x = abs(x)
  x = abs(z)
end program test_abs
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument            @tab Return type       @tab Standard
@item @code{CABS(Z)}  @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)}    @tab F77 and later
@item @code{DABS(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}    @tab F77 and later
@item @code{IABS(I)}  @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
@item @code{ZABS(Z)}  @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
@item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
@end multitable
@end table



@node ACCESS
@section @code{ACCESS} --- Checks file access modes
@fnindex ACCESS
@cindex file system, access mode

@table @asis
@item @emph{Description}:
@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 
exists, is readable, writable or executable. Except for the
executable check, @code{ACCESS} can be replaced by
Fortran 95's @code{INQUIRE}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = ACCESS(NAME, MODE)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
Tailing blank are ignored unless the character @code{achar(0)} is
present, then all characters up to and excluding @code{achar(0)} are
used as file name.
@item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,