F90_UNIX_FILE

Index

NAME
USAGE
SYNOPSIS
PARAMETER DESCRIPTION
DERIVED-TYPE DESCRIPTION
PROCEDURE DESCRIPTION
SEE ALSO
BUGS

NAME

f90_unix_file - Module of Unix file operations

USAGE

USE F90_UNIX_FILE

This module contains part of a Fortran API to functions detailed in ISO/IEC 9945-1:1990 Portable Operating System Interface (POSIX) - Part 1: System Application Program Interface (API) [C Language].

The functions in this module are from Section 5.6 File Characteristics.

Error handling is described in F90_UNIX_ERRNO. Note that for procedures with an optional ERRNO argument, if an error occurs and ERRNO is not present, the program will be terminated.

SYNOPSIS

Parameters: F_OK, MODE_KIND (from F90_UNIX_DIR), R_OK, S_IRGRP, S_IROTH, S_IRUSR, S_IRWXG, S_IRWXO, S_IRWXU, S_ISGID, S_ISUID, S_IWGRP, S_IWOTH, S_IWUSR, S_IXGRP, S_IXOTH, S_IXUSR, TIME_KIND (from F90_UNIX_ENV), W_OK, X_OK.
Derived Types: STAT_T, UTIMBUF.
Procedures: ACCESS, CHMOD, CHOWN, FSTAT, STAT, S_ISBLK, S_ISCHR, S_ISDIR, S_ISFIFO, S_ISREG, UTIME.

PARAMETER DESCRIPTION

INTEGER,PARAMETER :: F_OK

: Flag for requesting file existence check (see ACCESS).

USE F90_UNIX_DIR,ONLY:MODE_KIND

: See F90_UNIX_DIR for a description of this parameter.

INTEGER,PARAMETER :: R_OK

: Flag for requesting file readability check (see ACCESS).

INTEGER(MODE_KIND),PARAMETER :: S_IRGRP

: File mode bit indicating group read permission (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_IROTH

: File mode bit indicating other read permission (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_IRUSR

: File mode bit indicating user read permission (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_IRWXG

: Mask to select the group accessibility bits from a file mode (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_IRWXO

: Mask to select the other accessibility bits from a file mode (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_IRWXU

: Mask to select the user accessibility bits from a file mode (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_ISGID

: File mode bit indicating that the file is set-group-ID (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_ISUID

: File mode bit indicating that the file is set-user-ID (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_IWGRP

: File mode bit indicating group write permission (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_IWOTH

: File mode bit indicating other write permission (see STAT_T).

INTEGER,PARAMETER :: S_IWUSR

: File mode bit indicating user write permission (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_IXGRP

: File mode bit indicating group execute permission (see STAT_T).

INTEGER(MODE_KIND),PARAMETER :: S_IXOTH

: File mode bit indicating other execute permission (see STAT_T).

INTEGER,PARAMETER :: S_IXUSR

: File mode bit indicating user execute permission (see STAT_T).

USE F90_UNIX_ENV,ONLY :: TIME_KIND

: See F90_UNIX_ENV for a description of this parameter.

INTEGER,PARAMETER :: W_OK

: Flag for requesting file writability check (see ACCESS).

INTEGER,PARAMETER :: X_OK

: Flag for requesting file executability check (see ACCESS).

DERIVED-TYPE DESCRIPTION

TYPE STAT_T
       INTEGER(MODE_KIND) ST_MODE
       INTEGER(...) ST_INO
       INTEGER(...) ST_DEV
       INTEGER(...) ST_NLINK
       INTEGER(...) ST_UID
       INTEGER(...) ST_GID
       INTEGER(...) ST_SIZE
       INTEGER(TIME_KIND) ST_ATIME, ST_MTIME, ST_CTIME
END TYPE

Derived type holding file characteristics.

ST_MODE: File mode (read/write/execute permission for user/group/other, plus set-group-ID and set-user-ID bits).
ST_INO: File serial number.
ST_DEV: ID for the device on which the file resides.
ST_NLINK: The number of links (see F90_UNIX_DIR, LINK operation) to the file.
ST_UID: User number of the file's owner.
ST_GID: Group number of the file.
ST_SIZE: File size in bytes (regular files only).
ST_ATIME: Time of last access.
ST_MTIME: Time of last modification.
ST_CTIME: Time of last file status change.

TYPE UTIMBUF
INTEGER(TIME_KIND) ACTIME, MODTIME
END TYPE

: Data type holding time values for communication to UTIME. ACTIME is the new value for ST_ATIME, MODTIME is the new value for ST_MTIME.

PROCEDURE DESCRIPTION

PURE SUBROUTINE ACCESS(PATH,AMODE,ERRNO)
CHARACTER*(*),INTENT(IN) :: PATH
INTEGER,INTENT(IN) :: AMODE
INTEGER,INTENT(OUT) :: ERRNO

Checks file accessibility according to the value of AMODE; this should be F_OK or a combination of R_OK, W_OK and X_OK. In the latter case the values may be combined by addition or the IOR intrinsic.

The result of the accessibility check is returned in ERRNO, which receives zero for success (i.e. the file exists for F_OK, or all the accesses requested by the R_OK et al combination are allowed) or an error code indicating the reason for access rejection. Possible rejection codes include EACCES, ENAMETOOLONG, ENOENT, ENOTDIR, EROFS (see F90_UNIX_ERRNO).

If the value of AMODE is invalid, error EINVAL is returned.

Note that most ACCESS enquires are equivalent to an INQUIRE statement: in particular,

CALL ACCESS(PATH,F_OK,ERRNO) returns success (ERRNO==0) if and only if INQUIRE(FILE=PATH,EXIST=LVAR) would set LVAR to .TRUE..

CALL ACCESS(PATH,R_OK,ERRNO) returns success (ERRNO==0) if and only if INQUIRE(FILE=PATH,READ=CHVAR) would set CHVAR to "YES".

CALL ACCESS(PATH,W_OK,ERRNO) returns success (ERRNO==0) if and only if INQUIRE(FILE=PATH,WRITE=CHVAR) would set CHVAR to "YES".

CALL ACCESS(PATH,IOR(W_OK,R_OK),ERRNO) returns success (ERRNO==0) if and only if INQUIRE(FILE=PATH,READWRITE=CHVAR) would set CHVAR to "YES".

The only differences being that ACCESS returns a reason for rejection, and can test file executability.

SUBROUTINE CHMOD(PATH,MODE,ERRNO)
CHARACTER*(*),INTENT(IN) :: PATH
INTEGER(MODE_KIND),INTENT(IN) :: MODE
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

: Sets the file mode (ST_MODE) to MODE.
Possible errors include EACCES, ENAMETOOLONG, ENOTDIR, EPERM, EROFS (see F90_UNIX_ERRNO).

SUBROUTINE CHOWN(PATH,OWNER,GROUP,ERRNO)
CHARACTER*(*),INTENT(IN) :: PATH
INTEGER,INTENT(IN) :: OWNER, GROUP
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

: Changes the owner (ST_UID) of file PATH to OWNER, and the group number (ST_GID) of the file to GROUP.
Possible errors include EACCES, EINVAL, ENAMETOOLONG, ENOTDIR, ENOENT, EPERM, EROFS (see F90_UNIX_ERRNO).

SUBROUTINE FSTAT(LUNIT,BUF,ERRNO)
INTEGER,INTENT(IN) :: LUNIT
TYPE(STAT_T),INTENT(OUT) :: BUF
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

: BUF receives the characteristics of the file connected to logical unit LUNIT.
If LUNIT is not a valid logical unit number or is not connected to a file, error EBADF is raised (see F90_UNIX_ERRNO).

SUBROUTINE STAT(PATH,BUF,ERRNO)
CHARACTER*(*),INTENT(IN) :: PATH
TYPE(STAT_T),INTENT(OUT) :: BUF
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

: BUF receives the characteristics of the file PATH.
Possible errors include EACCES, ENAMETOOLONG, ENOENT, ENOTDIR (see F90_UNIX_ERRNO).

BUGS

Please report any bugs found to "support@nag.co.uk", along with any suggestions for improvements.