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 4: Process Environment, plus
gethostname
from 4.3BSD.
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.
All the procedures in this module are generic; some are also specific (this may change in a future release).
INTEGER(int32),PARAMETER :: clock_tick_kindThe integer kind used for clock ticks (see
TIMES
).
INTEGER(int32),PARAMETER :: id_kindInteger kind for representing IDs; that is, users (uids), groups (gids), process groups (pgids) and processes (pids).
INTEGER(int32),PARAMETER :: long_kindThe integer kind corresponding to the C type ‘long’. This is not actually used in this module, but is suitable for use when declaring a variable to receive a value from
SYSCONF
.
INTEGER(int32),PARAMETER :: sc_stdin_unit, sc_stdout_unit, sc_stderr_unit, sc_arg_max, sc_child_max, sc_clk_tck, sc_job_control, sc_open_max, sc_ngroups_max, sc_saved_ids, sc_stream_max, sc_tzname_max, sc_versionValues used as arguments to
SYSCONF
.
The following table describes the returned information from SYSCONF
,
this is not the value of the SC_*
constant.
SC_STDIN_UNIT
READ *,
...); this is the
same value as INPUT_UNIT
in the standard intrinsic module
ISO_FORTRAN_ENV
.
SC_STDOUT_UNIT
PRINT
,
WRITE(*,
...)
); this is the same value as OUTPUT_UNIT
in
the standard intrinsic module ISO_FORTRAN_ENV
.
SC_STDERR_UNIT
ERROR_UNIT
in the standard intrinsic module ISO_FORTRAN_ENV
.
SC_ARG_MAX
EXEC
functions, in bytes, including
environment data.
SC_CHILD_MAX
SC_CLK_TCK
CLK_TCK
function).
SC_JOB_CONTROL
SC_NGROUPS_MAX
SC_OPEN_MAX
SC_SAVED_IDS
SC_STREAM_MAX
SC_TZNAME_MAX
SC_VERSION
INTEGER(int32),PARAMETER :: time_kindThe integer kind used for holding date/time values (see
TIME
).
TYPE tms INTEGER(clock_tick_kind) utime, stime, cutime, cstime END TYPEDerived type holding CPU usage time in clock ticks.
UTIME
and
STIME
contain CPU time information for a process, CUTIME
and
CSTIME
contain CPU time information for its terminated child processes.
In each case this is divided into user time (UTIME
, CUTIME
) and
system time (STIME
, CSTIME
).
TYPE utsname CHARACTER(...) sysname, nodename, release, version, machine END TYPEDerived type holding data returned by
UNAME
.
Note that the character length of each component is fixed, but may be
different on different systems.
The values in these components are blank-padded (if short) or truncated
(if long).
For further information see ISO/IEC 9945-1:1990.
PURE INTEGER(KIND=clock_tick_kind) FUNCTION clk_tck()Returns the number of clock ticks in one second of CPU time (see
TIMES
).
PURE SUBROUTINE ctermid(s,lens) CHARACTER(*),OPTIONAL,INTENT(OUT) :: s INTEGER(int32),OPTIONAL,INTENT(OUT) :: lensIf present,
S
is set to the filename of the controlling terminal.
If present, LENS
is set to the length of the filename of the controlling
terminal.
If S
is longer than the filename of the controlling terminal it is
padded with blanks; if S
is shorter it is truncated — it is the user's
responsibility to check the value of LENS
to detect such truncation.
If the filename of the controlling terminal cannot be determined for any
reason LENS
(if present) will be set to zero and S
(if present)
will be blank.
SUBROUTINE getarg(k,arg,lenarg,errno) INTEGER(*),INTENT(IN) :: k CHARACTER(*),OPTIONAL,INTENT(OUT) :: arg INTEGER(int32),OPTIONAL,INTENT(OUT) :: lenarg INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoAccesses command-line argument number
K
, where argument zero is the
program name.
If ARG
is present, it receives the argument text (blank-padded or
truncated as appropriate if the length of the argument differs from that of
ARG
).
If LENARG
is present, it receives the length of the argument.
If ERRNO
is present, it receives the error status.
Note that if K
is less than zero or greater than the number of arguments
(returned by IARGC
) error EINVAL
(see F90_UNIX_ERRNO
) is
raised.
This procedure is very similar to the standard intrinsic procedure
GET_COMMAND_ARGUMENT
.
PURE INTEGER(id_kind) FUNCTION getegid()Returns the effective group number of the calling process.
SUBROUTINE getenv(name,value,lenvalue,errno) CHARACTER(*),INTENT(IN) :: name CHARACTER(*),OPTIONAL,INTENT(OUT) :: value INTEGER(int32),OPTIONAL,INTENT(OUT) :: lenvalue INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoAccesses the environment variable named by
NAME
.
If VALUE
is present, it receives the text value of the variable
(blank-padded or truncated as appropriate if the length of the value differs
from that of VALUE
).
If LENVALUE
is present, it receives the length of the value.
If ERRNO
is present, it receives the error status.
If there is no such variable, error EINVAL
(see F90_UNIX_ERRNO
)
is raised.
Other possible errors include ENOMEM
.
PURE INTEGER(id_kind) FUNCTION geteuid()Returns the effective user number of the calling process.
PURE INTEGER(id_kind) FUNCTION getgid()Returns the group number of the calling process.
SUBROUTINE getgroups(grouplist,ngroups,errno) INTEGER(id_kind),OPTIONAL,INTENT(OUT) :: grouplist(:) INTEGER(int32),OPTIONAL,INTENT(OUT) :: ngroups INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoRetrieves supplementary group number information for the calling process. If
GROUPLIST
is present, it is filled with the supplementary group
numbers.
If NGROUPS
is present, it receives the number of supplementary group
numbers.
If ERRNO
is present, it receives the error status.
If GROUPLIST
is present but too small to contain the complete list of
supplementary group numbers, error EINVAL
(see F90_UNIX_ERRNO)
is
raised.
The maximum number of supplementary group numbers can be found using
SYSCONF
(enquiry SC_NGROUPS_MAX
); alternatively,
‘CALL GETGROUPS(NGROUPS=N)
’ will reliably return the actual
number in use.
PURE SUBROUTINE gethostname(name,lenname) CHARACTER(*),OPTIONAL,INTENT(OUT) :: name INTEGER(int32),OPTIONAL,INTENT(OUT) :: lennameThis provides the functionality of 4.3BSD's gethostname. If
NAME
is present it receives the text of the standard host name for the
current processor, blank-padded or truncated if appropriate.
If LENNAME
is present it receives the length of the host name.
If no host name is available LENNAME
will be zero.
PURE SUBROUTINE getlogin(s,lens) CHARACTER(*),OPTIONAL,INTENT(OUT) :: s INTEGER(int32),OPTIONAL,INTENT(OUT) :: lensAccesses the user name (login name) associated with the calling process. If
S
is present, it receives the text of the name (blank-padded or
truncated as appropriate if the length of the login name differs from that of
S
).
If LENS
is present, it receives the length of the login name.
PURE INTEGER(id_kind) FUNCTION getpgrp()Returns the process group number of the calling process.
PURE INTEGER(id_kind) FUNCTION getpid()Returns the process number of the calling process.
PURE INTEGER(id_kind) FUNCTION getppid()Returns the process number of the parent of the calling process.
PURE INTEGER(id_kind) FUNCTION getuid()Returns the user number of the calling process.
PURE INTEGER(int32) FUNCTION iargc()Returns the number of command-line arguments; this is the same value as the intrinsic function
COMMAND_ARGUMENT_COUNT
, except that it returns -1 if
even the program name is unavailable (the intrinsic function erroneously
returns the same value, 0, whether the program name is available or not).
SUBROUTINE isatty(lunit,answer,errno) INTEGER(*),INTENT(IN) :: lunit LOGICAL(*),INTENT(OUT) :: answer INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errno
ANSWER
receives the value .TRUE.
if and only if the logical unit
identified by LUNIT
is connected to a terminal.
If LUNIT
is not a valid unit number or is not connected to any file,
error EBADF
(see F90_UNIX_ERRNO
) is raised.
SUBROUTINE setgid(gid,errno) INTEGER(*),INTENT(IN) :: gid INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoSets the group number of the calling process to
GID
.
For full details refer to section 4.2.2 of ISO/IEC 9945-1:1990.
If GID
is not a valid group number, error EINVAL
(see
F90_UNIX_ERRNO
) is raised.
If the process is not allowed to set the group number to GID
,
error EPERM
is raised.
SUBROUTINE setpgid(pid,pgid,errno) INTEGER(*),INTENT(IN) :: pid, pgid INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoSets the process group number of process
PID
(or, if PID
is zero,
the calling process) to PGID
.
For full details refer to section 4.3.3 of ISO/IEC 9945-1:1990.
Possible errors include EACCES
, EINVAL
, ENOSYS
,
EPERM
, ESRCH
(see F90_UNIX_ERRNO
).
SUBROUTINE setsid(sid,errno) INTEGER(id_kind),OPTIONAL,INTENT(OUT) :: sid INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoCreates a session and sets the process group number of the calling process. For full details refer to section 4.3.2 of ISO/IEC 9945-1:1990. If
SID
is present it receives the new session id (equal to the process
id); if an error occurs it receives -1.
Possible errors include EPERM
(see F90_UNIX_ERRNO
).
SUBROUTINE setuid(uid,errno) INTEGER(*),INTENT(IN) :: uid INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoSets the user number of the calling process to
UID
.
For full details refer to section 4.2.2 of ISO/IEC 9945-1:1990.
If UID
is not a valid group number, error EINVAL
(see
F90_UNIX_ERRNO
) is raised.
If the process is not allowed to set the user number to UID
, error
EPERM
is raised.
SUBROUTINE sysconf(name,val,errno) INTEGER(*),INTENT(IN) :: name INTEGER(*),INTENT(OUT) :: val INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoReturns the value of a system configuration variable. The variables are named by integer PARAMETERs defined in this module, and are described in the Parameters section.
If NAME
is not a valid configuration variable name, error EINVAL
(see F90_UNIX_ERRNO
) is raised.
If VAL
is too small an integer kind to contain the result,
error ERANGE
is raised; kind LONG_KIND
is guaranteed to be big
enough for all values.
SUBROUTINE time(itime,errno) INTEGER(time_kind),INTENT(OUT) :: itime INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errno
ITIME
receives the operating system date/time in seconds since the Epoch.
INTEGER(KIND=clock_tick_kind) FUNCTION times(buffer) TYPE(tms),INTENT(OUT) :: bufferThis function returns the elapsed real time in clock ticks since an arbitrary point in the past, or -1 if the function is unavailable.
BUFFER
is filled in with CPU time information for the calling process
and any terminated child processes.
If this function returns zero the values in BUFFER
will still be correct
but the elapsed-time timer was not available.
SUBROUTINE ttyname(lunit,s,lens,errno) INTEGER(*),INTENT(IN) :: lunit CHARACTER(*),OPTIONAL,INTENT(OUT) :: s INTEGER(int32),OPTIONAL,INTENT(OUT) :: lens INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoAccesses the name of the terminal connected to the logical unit identified by
LUNIT
.
If S
is present, it receives the text of the terminal name (blank-padded
or truncated as appropriate, if the length of the terminal name differs from
that of S
).
If LENS
is present, it receives the length of the terminal name.
If ERRNO
is present, it receives the error status.
If LUNIT
is not a valid logical unit number, or is not connected, error
EBADF
(see F90_UNIX_ERRNO
) is raised; otherwise, if the function
is not available, ENOSYS
is raised, or if LUNIT
is not connected
to a terminal, error ENOTTY
is raised.
SUBROUTINE uname(name,errno) TYPE(UTSNAME),INTENT(OUT) :: name INTEGER(error_kind),OPTIONAL,INTENT(OUT) :: errnoReturns information about the operating system in
NAME
.