This appendix describes the functions and subroutines in the Fortran run-time library which are known as 3F routines on many systems. These routines provide an interface from pgf77 programs to the system in the same manner as the C library does for pgcc programs. These functions and subroutines are automatically loaded from the PGI 's Fortran run-time library if referenced by a pgf77 program.
The implementation of many of the routines uses functions which reside in the C library. If a C library does not contain the necessary functions, undefined symbol errors will occur at link-time. For example, if PGI 's C library is the C library available on the system, the following 3F routines exist in the Fortran run-time library but use of these routines will result in errors at link-time:
besj0
|
dbesyn
|
| besj1
|
derf
|
| besjn
|
derfc
|
| besy0
|
erf
|
| besy1
|
erfc
|
| besyn
|
getlog
|
| dbesj0
|
hostnm
|
| dbesj1
|
lstat
|
| dbesjn
|
putenv
|
| dbesy0
|
symlnk
|
| dbesy1
|
ttynam
|
The routines dtime and etime are only available in a SYSVR4 environment. These routines are not available in all environments simply because there is no standard mechanism to resolve the resolution of the value returned by the times() function.
There are several 3F routines (for example, fputc and fgetc ) which perform I/O on a logical unit. These routines bypass normal Fortran I/O. If normal Fortran I/O is also performed on a logical unit which ears in any of these routines, the results are unpredictable.
Terminate abruptly and write memory image to core file.
Synopsis
subroutine abort()
Description
abort cleans up the I/O buffers and then aborts, producing a core file in the current directory.
Determine access mode or existence of a file.
Synopsis
integer function access(fil, mode)
character*(*) fil
character*(*) mode
Description
The access function if the file, whose name is fil , for accessibility or existence as determined by mode.
The mode argument may include, in any order and in any combination, one or more of:
Execute a subroutine after a specified time.
Synopsis
integer function alarm(time, proc)
integer time
external proc
Description
This routine establishes subroutine proc to be called after time seconds. If time is 0, the alarm is turned off and no routine will be called. The return value of alarm is the time remaining on the last alarm.
These functions calculate Bessel functions of the first and second kinds for real and double precision arguments and integer orders.
besj0 |
besj1 |
besjn |
besy0 |
besy1 |
besyn |
dbesj0 |
dbesj1 |
dbesjn |
dbesy0 |
dbesy1 |
dbesyn |
Synopsis
real function besj0(x)
real x real function besj1(x)
real x real function besjn(n, x)
integer n
real x real function besy0(x)
real x real function besy1(x)
real x real function besyn(n, x)
integer n
real x double precision function dbesj0(x)
double precision x double precision function dbesj1(x)
double precision x double precision function dbesjn(n, x)
integer n
double precision x double precision function dbesy0(x)
double precision x double precision function dbesy1(x)
double precision x double precision function dbesyn(n, x)
integer n
double precision x
Synopsis
integer function chdir(path)
character*(*) path
Description
Change the default directory for creating and locating files to path. Zero is returned if successful; otherwise, an error code is returned.
Synopsis
integer function chmod(nam, mode)
character*(*) nam
integer mode
Description
Change the file system mode of file nam If successful, a value of 0 is returned; otherwise, an error code is returned.
Synopsis
character*(*) function ctime(stime)
integer stime
Description
ctime converts a system time in stime to its ASCII form and returns the converted form. Neither newline nor NULL are included.
Synopsis
character*(*) function date(buf)
Description
Returns the ASCII representation of the current date. The form returned is dd-mmm-yy.
The functions erf and derf return the error function of x. erfc and derfc return 1.0-erf(x) and 1.0-derf(x), respectively.
Synopsis
real function erf(x)
real x real function erfc(x)
real x double precision function derf(x)
double precision x double precision function derfc(x)
double precision x
Synopsis
real function etime(tarray)
real function dtime(tarray)
real tarray(2)
Description
etime returns the total processor run-time in seconds for the calling process.
dtime (delta time) returns the processor time since the previous call to dtime. The first time it is called, it returns the processor time since the start of execution.
Both functions place values in the argument tarray : user time in the first element and system time in the second element. The return value is the sum of these two times.
Terminate program with status.
Synopsis
subroutine exit(s)
integer s
Description
exit flushes and closes all of the program's files, and returns the value of s to the parent process.
Return date and time in ASCII form.
Synopsis
character*(*) function fdate()
Description
fdate returns the current date and time as a character string. Neither newline nor NULL will be included.
Get character from a logical unit.
Synopsis
integer function fgetc(lu, ch)
integer lu
character*(*) ch
Description
Returns the next character in ch from the file connected to the logical unit lu, bypassing normal Fortran I/O statements. If successful, the return value is zero; -1 indicates that an end-of-file was detected. Any other value is an error code.
Synopsis
subroutine flush(lu)
integer lu
Description
flush flushes the contents of the buffer associated with logical unit lu.
Synopsis
integer function fork()
Description
fork creates a copy of the calling process. The value returned to the parent process will be the process id of the copy. The value returned to the child process (the copy) will be zero. If the returned value is negative, an error occurred and the value is the negation of the system error code.
Write a character to a logical unit.
Synopsis
integer function fputc(lu, ch)
integer lu
character*(*) ch
Description
A character ch is written to the file connected to logical unit lu bypassing normal Fortran I/O. If successful, a value of zero is returned; otherwise, an error code is returned.
Synopsis
subroutine free(p)
int p
Description
Free a pointer to a block of memory located by malloc; the value of the argument, p , is the pointer to the block of memory.
Synopsis
integer function fseek(lu, offset, from)
integer lu
integer offset
integer from
Description
fseek repositions a file connected to logical unit lu. offset is an offset in bytes relative to the position specified by from :
Synopsis
integer function ftell(lu)
integer lu
Description
ftell returns the current position of the file connected to the logical unit lu. The value returned is an offset, in units of bytes, from the beginning of the file. If the value returned is negative, it is the negation of the system error code.
Synopsis
character*(*) function gerror()
Description
Return the system error message of the last detected system error.
Get the n th command line argument.
Synopsis
subroutine getarg(n, arg)
integer n
character*(*) arg
Description
Return the n th command line argument in arg, where the 0 th argument is the command name.
Index of the last command line argument.
Synopsis
integer function iargc()
Description
Return the index of the last command line argument, which is also the number of arguments after the command name.
Synopsis
integer function getc(ch)
character*(*) ch
Description
Returns the next character in ch from the file connected to the logical unit 5, bypassing normal Fortran I/O statements. If successful, the return value is zero; -1 indicates that an end-of-file was detected. Any other value is an error code.
Get pathname of current working directory.
Synopsis
integer function getcwd(dir)
character*(*) dir
Description
The pathname of the current working directory is returned in dir. If successful, the return value is zero; otherwise, an error code is returned.
Get value of environment variable.
Synopsis
subroutine getenv(en, ev)
character*(*) en
character*(*) ev
Description
getenv checks for the existence of the environment variable en. If it does not exist or if its value is not present, ev is filled with blanks. Otherwise, the value, a string, of en is returned in ev.
Synopsis
integer function getgid()
Description
Return the group id of the user of the process.
Synopsis
character*(*) function getlog()
Description
getlog returns the user's login name or blanks if the process is running detached from a terminal.
Synopsis
integer function getpid()
Description
Return the process id of the current process.
Synopsis
integer function getuid()
Description
Return the user id of the user of the process.
Synopsis
subroutine gmtime(stime, tarray)
integer stime
integer tarray(9)
Description
Dissect the UNIX time, stime , into month, day, etc., for GMT and return in tarray.
Synopsis
integer function hostnm(nm)
character*(*) nm
Description
hostnm returns the name of the current host in nm. If successful, a value of zero is returned; otherwise an error occurred.
Return date in numerical form.
Synopsis
subroutine idate(im, id, iy)
integer im, id, iy
Description
Returns the current date in the variables im , id , and iy , which indicate the month, day, and year, respectively. The month is in the range 1-12; only the last 2 digits of the year are returned.
Synopsis
integer function ierrno()
Description
Return the number of the last detected system error.
Synopsis
subroutine ioinit(cctl, bzro, apnd, prefix, vrbose) integer cctl
integer bzro
integer apnd
character*(*) prefix
integer vrbose
Description
Currently, no action is performed.
Synopsis
logical function isatty(lu)
integer lu
Description
Returns .TRUE. if logical unit lu is connected to a terminal; otherwise, .FALSE. is returned.
Return time in numerical form.
Synopsis
subroutine itime(iarray)
integer iarray(3)
Description
Return in current time in the array iarray. The order is hour, minute, and second.
Synopsis
integer function kill(pid, sig)
integer pid
integer sig
Description
Send signal number sig to the process whose process id is pid. If successful, the value zero is returned; otherwise, an error code is returned.
Synopsis
integer function link(n1, n2)
character*(*) n1
character*(*) n2
Description
Create a link n2 to an existing file n1. If successful, zero is returned; otherwise, an error code is returned.
Return index of last non-blank.
Synopsis
integer function lnblnk(a1)
character*(*) a1
Description
Return the index of the last non-blank character in string a1.
Synopsis
integer function loc(a)
integer a
Description
Return the value which is the address of a.
Synopsis
subroutine ltime(stime, tarray)
integer stime
integer tarray(9)
Description
Dissect the UNIX time, stime , into month, day, etc., for the local time zone and return in tarray.
Synopsis
integer function malloc(n)
integer n
Description
Allocate a block of n bytes of memory and return the pointer to the block of memory.
Synopsis
integer function mclock()
Description
mclock returns the sum of the user's cpu time and the user and system times of all child processes. The return value is in units of clock ticks per second.
Synopsis
subroutine mvbits(src, pos, len, dest, posd)
integer src
integer pos
integer len
integer dest
integer posd
Description
len bits are moved beginning at position pos of argument src to position posd of argument dest.
Synopsis
integer function outstr(ch)
character*(*) ch
Description
Output the character string to logical unit 6 bypassing normal Fortran I/O. If successful, a value of zero is returned; otherwise, an error occurred.
Synopsis
subroutine perror(str)
character*(*) str
Description
Write the message indicated by str to logical unit 0 and the message for the last detected system error.
Write a character to logical unit 6.
Synopsis
integer function putc(ch)
character*(*) ch
Description
A character ch is written to the file connected to logical unit 6 bypassing normal Fortran I/O. If successful, a value of zero is returned; otherwise, an error code is returned.
Change or add environment variable.
Synopsis
integer function putenv(str)
character*(*) str
Description
str contains a character string of the form name=value. This function makes the value of the environment variable name equal to value.
If successful, zero is returned.
Synopsis
subroutine qsort(array, len, isize, compar)
dimension array(*)
integer len
integer isize
external compar
integer compar
Description
qsort sorts the elements of the one dimensional array, array. len is the number of elements in the array and isize is the size of an element. compar is the name of an integer function that determines the sorting order. This function is called with 2 arguments ( arg1 and arg2 ) which are elements of array. The function returns:
Synopsis
double precision function rand() integer function irand() subroutine srand(iseed)
integer iseed
Description
The functions rand and irand generates successive pseudo-random integers or double precision numbers. srand uses its argument, iseed , to re-initialize the seed for successive invocations of rand and irand.
irand returns a positive integer in the range 0 through 2147483647.
rand returns a value in the range 0 through 1.0.
Return the next random number value. If the argument, flag , is nonzero, the random number generator is restarted before the next random number is generated. Integer values will range from 0 thru 2147483647; floating point values will range from 0.0 thru 1.0.
Synopsis
real function random(flag) integer flag
integer function irandm(flag)
integer flag
double precision function drandm(flag)
integer flag
Synopsis
real function flmin() real function flmax() real function ffrac() double precision function dflmin() double precision function dflmax() double precision function dffrac() integer function inmax()
Description
Synopsis
integer function rename(from, to)
character*(*) from
character*(*) to
Description
Rename the existing file from where the new name is to. If successful, zero is returned; otherwise, the return value is an error code.
Synopsis
integer function rindex(a1, a2)
character*(*) a1
character*(*) a2
Description
Return the index of the last occurrence of string a2 in string a1.
Synopsis
real function secnds(x)
real x double precision function dsecnds(x) double precision x
Description
Returns the elapsed time in units of seconds since midnight, minus the value of x.
Synopsis
integer function signal(signum, proc, flag) integer signum
external proc
integer flag
Description
signal allows the calling process to choose how the receipt of a specific signal is handled; signum is the signal and proc is the choice. If flag is negative, proc is a Fortran subprogram and is established as the signal handler for the signal. Otherwise, proc is ignored and the value of flag is passed to the system as the signal action definition. In particular, this how previously saved signal actions can be restored. There are two special cases of flag : 0 means use the default action and 1 means ignore this signal.
The return value is the previous action. If this is a value greater than one, then it is the address of a routine that was to have been called. The return value can be used in subsequent calls to signal to restore a previous action. A negative returned value indicates a system error.
Suspend execution for a period of time.
Synopsis
subroutine sleep(itime)
integer itime
Description
Suspends the process for t seconds.
Synopsis
integer function stat(nm, statb)
character*(*) nm
integer statb(*) integer function lstat(nm, statb)
character*(*) nm
integer statb(*)
integer function fstat(lu, statb)
integer lu
integer statb(*)
Description
Return the file status of the file in the array statb. If successful, zero is returned; otherwise, the value of -1 is returned. stat obtains information about the file whose name is nm ; if the file is a symbolic link, information is obtained about the file the link references. lstat is similar to stat except lstat returns information about the link. fstat obtains information about the file which is connected to logical unit lu.
Synopsis
integer function stime(tp)
integer tp
Description
Set the system time and date. tp is the value of the time measured in seconds from 00:00:00 GMT January 1, 1970.
Synopsis
integer function symlnk(n1, n2)
character*(*) n1 character*(*) n2
Description
Create a symbolic link n2 to an existing file n1. If successful, zero is returned; otherwise, an error code is returned.
Synopsis
integer function system(str)
character*(*) str
Description
system causes the string, str , to be given to the shell as input. The current process waits until the shell has completed and returns the exit status of the shell.
Synopsis
integer function time()
Description
Return the time since 00:00:00 GMT, January 1, 1970, measured in seconds.
Get process and child process time
Synopsis
integer function times(buff)
integer buff(*)
Description
Returns the time-accounting information for the current process and for any terminated child processes of the current process in the array buff. If successful, zero is returned; otherwise, the negation of the error code is returned.
Synopsis
character*(*) ttynam(lu) integer lu
Description
Returns a blank padded path name of the terminal device connected to the logical unit lu. The lu is not connected to a terminal, blanks are returned.
Synopsis
integer function unlink(fil)
character*(*) fil
Description
Removes the file specified by the pathname fil. If successful, zero is returned; otherwise, an error code is returned.
Wait for process to terminate.
Synopsis
integer function wait(st)
integer st
Description
wait causes its caller to be suspended until a signal is received or one its child processes terminates. If any child has terminated since the last wait , return is immediate. If there are no child processes, return is immediate with an error code.
If the return value is positive, it is the process id of the child and st is its termination status. If the return value is negative, it is the negation of an error code.