F90_UNIX_PROC

Index

NAME
USAGE
SYNOPSIS
PARAMETER DESCRIPTION
PROCEDURE DESCRIPTION
GENERIC PROCEDURE DESCRIPTION
SEE ALSO
BUGS

NAME

f90_unix_proc - Module of Unix process primitives

USAGE

USE F90_UNIX_PROC

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 3: Process Primitives, excluding 3.3 Signals. The C language functions ABORT, ATEXIT, EXIT and SYSTEM are also provided by this module.

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: PID_KIND, WNOHANG, WUNTRACED.
Procedures: ABORT, ALARM, ATEXIT, EXECV, EXECVE, EXECVP, EXIT, FASTEXIT, FORK, PAUSE, SLEEP, WAIT, WAITPID, WEXITSTATUS, WIFEXITED, WIFSIGNALED, WIFSTOPPED, WSTOPSIG, WTERMSIG.
Generic Procedures: EXECL, EXECLP.

PARAMETER DESCRIPTION

INTEGER,PARAMETER :: PID_KIND

: Integer kind for representing process IDs.

INTEGER,PARAMETER :: WNOHANG

: Option bit for WAITPID indicating that the calling process should not wait for the child process to stop or exit.

INTEGER,PARAMETER :: WUNTRACED

: Option bit for WAITPID indicating that status should be returned for stopped processes as well as terminated ones.

PROCEDURE DESCRIPTION

SUBROUTINE ABORT(message)
CHARACTER*(*), OPTIONAL :: message

: ABORT cleans up the i/o buffers and then terminates execution, producing a core dump on Unix systems. If MESSAGE is given it is written to logical unit 0 (zero) preceded by " abort:".

SUBROUTINE ALARM(SECONDS,SUBROUTINE,SECLEFT)
INTEGER,INTENT(IN) :: SECONDS
INTERFACE

SUBROUTINE SUBROUTINE()

END
END INTERFACE
OPTIONAL SUBROUTINE
INTEGER,OPTIONAL,INTENT(OUT) :: SECLEFT

: Establishes an "alarm" call to the procedure SUBROUTINE to occur after SECONDS seconds have passed, or cancels an existing alarm if SECONDS==0. If SUBROUTINE is not present, the previous associated of a subroutine with the alarm signal is left unchanged. If SECLEFT is present, it receives the number of seconds that were left on the preceding alarm or zero if there were no existing alarm.
If an alarm call is established with no handler (i.e. SUBROUTINE was not present on the first call) the process may be terminated when the alarm goes off.

SUBROUTINE ATEXIT(SUBROUTINE,ERRNO)
INTERFACE
SUBROUTINE SUBROUTINE()
END
END INTERFACE
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

Registers an argumentless subroutine for execution on normal termination of the program.

If the program terminates normally, all subroutines registered with ATEXIT will be invoked in reverse order of their registration. Normal termination includes using the F90_UNIX_PROC procedure EXIT, executing a Fortran STOP statement or executing a main program END statement. ATEXIT subroutines are invoked before automatic file closure.

If the program terminates due to an error or by using the F90_UNIX_PROC procedure FASTEXIT, these subroutines will not be invoked. Possible errors include ENOMEM. Note: The list of ATEXIT procedures registered via Fortran is separate from those registered via C; the latter will be invoked after all files have been closed.

SUBROUTINE EXECV(PATH,ARGV,LENARGV,ERRNO)
CHARACTER*(*),INTENT(IN) :: PATH
CHARACTER*(*),INTENT(IN) :: ARGV(:)
INTEGER,INTENT(IN) :: LENARGV(:)
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

: Executes the file PATH in place of the current process image; for full details see ISO/IEC 9945-1:1990 section 3.1.2. ARGV is the array of argument strings, LENARGV containing the desired length of each argument. If ARGV is not zero-sized, ARGV(1)(:LENARGV(1)) is passed as argument zero (i.e. the program name).
If LENARGV is not the same shape as ARGV, error EINVAL is raised (see F90_UNIX_ERRNO). Other possible errors include E2BIG, EACCES, ENAMETOOLONG, ENOENT, ENOTDIR, ENOEXEC, ENOMEM.

SUBROUTINE EXECVE(PATH,ARGV,LENARGV,ENV,LENENV,ERRNO)
CHARACTER*(*),INTENT(IN) :: PATH
CHARACTER*(*),INTENT(IN) :: ARGV(:)
INTEGER,INTENT(IN) :: LENARGV(:)
CHARACTER*(*),INTENT(IN) :: ENV(:)
INTEGER,INTENT(IN) :: LENENV(:)
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

: Similar to EXECV, with the environment strings specified by ENV and LENENV being passed to the new program; for full details see ISO/IEC 9945-1:1990 section 3.1.2.
If LENARGV is not the same shape as ARGV or LENENV is not the same shape as LENENV, error EINVAL is raised (see F90_UNIX_ERRNO). Other errors are the same as for EXECV.

SUBROUTINE EXECVP(FILE,ARGV,LENARGV,ERRNO)
CHARACTER*(*),INTENT(IN) :: FILE
CHARACTER*(*),INTENT(IN) :: ARGV(:)
INTEGER,INTENT(IN) :: LENARGV(:)
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

: The same as EXECV except that the program to be executed, FILE, is searched for using the PATH environment variable (unless it contains a slash character, in which case EXECVP is identical in effect to EXECV).
Errors are the same as for EXECV.

SUBROUTINE EXIT(STATUS)
INTEGER,OPTIONAL :: STATUS

: Terminate execution as if executing the END statement of the main program (or an unadorned STOP statement). If STATUS is given it is returned to the operating system (where applicable) as the execution status code.

SUBROUTINE FASTEXIT(STATUS)
INTEGER,OPTIONAL :: STATUS

This provides the functionality of ISO/IEC 9945-1:1990 function _exit (section 3.2.2). There are two main differences between FASTEXIT and EXIT:

(1): When EXIT is called all open logical units are closed (as if by a CLOSE statement). With FASTEXIT this is not done, nor are any file buffers flushed, thus the contents and status of any file connected at the time of calling FASTEXIT are undefined.
(2): Subroutines registered with ATEXIT are not executed.

SUBROUTINE FORK(PID,ERRNO)
INTEGER(PID_KIND),INTENT(OUT) :: PID
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

: Creates a new process which is an exact copy of the calling process. In the new process, the value returned in PID is zero; in the calling process the value returned in PID is the process ID of the new (child) process.
Possible errors include EAGAIN and ENOMEM (see F90_UNIX_ERRNO).

SUBROUTINE PAUSE(ERRNO)
INTEGER,INTENT(OUT) :: ERRNO

: Suspends process execution until a signal is raised. If the action of the signal was to terminate the process, the process is terminated without returning from PAUSE. If the action of the signal was to invoke a signal handler (e.g. via ALARM), process execution continues after return from the signal handler.
If process execution is continued after a signal, ERRNO is set to EINTR.

PURE SUBROUTINE SLEEP(SECONDS,SECLEFT)
INTEGER,INTENT(IN) :: SECONDS
INTEGER,OPTIONAL,INTENT(OUT) :: SECLEFT

: Suspends process execution for SECONDS seconds, or until a signal has been delivered. If SECLEFT is present, it receives the number of seconds remaining in the sleep time (zero unless the sleep was interrupted by a signal).

SUBROUTINE SYSTEM(STRING,STATUS,ERRNO)
CHARACTER*(*),INTENT(IN) :: STRING
INTEGER,OPTIONAL,INTENT(OUT) :: STATUS,ERRNO

: Passes STRING to the command processor for execution. If STATUS is present it receives the completion status - this is the same status returned by "WAIT" and can be decoded with WIFEXITED etc. If ERRNO is present it receives the error status from the SYSTEM call itself.
Possible errors are those from FORK or EXECV.

SUBROUTINE WAIT(STATUS,RETPID,ERRNO)
INTEGER,OPTIONAL,INTENT(OUT) :: STATUS
INTEGER(PID_KIND),OPTIONAL,INTENT(OUT) :: RETPID
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

Wait for any child process to terminate (returns immediately if one has already terminated). See ISO/IEC 9945-1:1990 section 3.2.1 for full details.

If STATUS is present it receives the termination status of the child process. If RETPID is present it receives the process number of the child process.

Possible errors include ECHILD, EINTR (see F90_UNIX_ERRNO).

SUBROUTINE WAITPID(PID,STATUS,OPTIONS,RETPID,ERRNO)
INTEGER(PID_KIND),INTENT(IN) :: PID
INTEGER,OPTIONAL,INTENT(OUT) :: STATUS, RETPID, ERRNO
INTEGER,OPTIONAL,INTENT(IN) :: OPTIONS

: Wait for a particular child process to terminate (or for any one if PID.EQ.-1). If OPTIONS is not present it is as if it were present with a value of 0. See ISO/IEC 9945-1:1990 section 3.2.1 for full details.
Possible errors include ECHILD, EINTR, EINVAL (see F90_UNIX_ERRNO).

PURE INTEGER FUNCTION WEXITSTATUS(STAT_VAL)
INTEGER,INTENT(IN) :: STAT_VAL

: If WIFEXITED(STAT_VAL) is .TRUE., this function returns the low-order 8 bits of the status value supplied to EXIT or FASTEXIT by the child process. If the child process executed a STOP statement or main program END statement, the value will be zero. If WIFEXITED(STAT_VAL) is .FALSE., the function value is undefined.

PURE LOGICAL FUNCTION WIFEXITED(STAT_VAL)
INTEGER,INTENT(IN) :: STAT_VAL

: Returns .TRUE. if and only if the child process terminated by calling FASTEXIT, EXIT, or by executing a STOP statement or main program END statement.

PURE LOGICAL FUNCTION WIFSIGNALED(STAT_VAL)
INTEGER,INTENT(IN) :: STAT_VAL

: Returns .TRUE. if and only if the child process terminated by receiving a signal that was not caught.

PURE LOGICAL FUNCTION WIFSTOPPED(STAT_VAL)
INTEGER,INTENT(IN) :: STAT_VAL

: Returns .TRUE. if and only if the child process is stopped (and not terminated). Note that WAITPID must have been used with the WUNTRACED option to receive such a status value.

PURE INTEGER FUNCTION WSTOPSIG(STAT_VAL)
INTEGER,INTENT(IN) :: STAT_VAL

: If WIFSTOPPED(STAT_VAL) is .TRUE., this function returns the signal number that caused the child process to stop. If WIFSTOPPED(STAT_VAL) is .FALSE., the function value is undefined.

PURE INTEGER FUNCTION WTERMSIG(STAT_VAL)
INTEGER,INTENT(IN) :: STAT_VAL

: If WIFSIGNALED(STAT_VAL) is .TRUE., this function returns the signal number that caused the child process to terminate. If WIFSIGNALED(STAT_VAL) is .FALSE., the function value is undefined.

GENERIC PROCEDURE DESCRIPTION

SUBROUTINE EXECL(PATH,ARG0...,ERRNO)
CHARACTER*(*),INTENT(IN) :: PATH
CHARACTER*(*),INTENT(IN) :: ARG0...
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO

Arguments are named ARG0, ARG1, etc. up to ARG20 (additional arguments may be provided in later releases).

: This function is the same as EXECV except that the arguments are provided individually instead of via an array; and because they are provided individually, there is no need to provide the lengths (the lengths being taken from each argument itself).
Errors are the same as for EXECV.

SUBROUTINE EXECLP(FILE,arguments,,ERRNO)
CHARACTER*(*),INTENT(IN) :: FILE
CHARACTER*(*),INTENT(IN) :: arguments
INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO