<< " border=0>

C 3F Functions

• abort
• access
• alarm
• Bessel functions
• chdir
• chmod
• ctime
• date
• error functions
• etime, dtime
• exit
• fdate
• fgetc
• flush
• fork
• fputc
• free
• fseek
• ftell
• gerror
• getarg
• iargc
• getc
• getcwd
• getenv
• getgid
• getlog
• getpid
• getuid
• gmtime
• hostnm
• idate
• ierrno
• ioinit
• isatty
• itime
• kill
• link
• lnblnk
• loc
• ltime
• malloc
• mclock
• mvbits
• outstr
• perror
• putc
• putenv
• qsort
• rand, irand, srand
• random, irandm, drandm
• range
• rename
• rindex
• secnds, dsecnds
• signal
• sleep
• stat, lstat, fstat
• stime
• symlnk
• system
• time
• times
• ttynam
• unlink
• wait

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:

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.

abort

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.

access

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:

r

test for read permission

w

test for write permission

x

test for execute permission

(blank)

test for existence

alarm

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.

Bessel functions

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

chdir

Change default directory.

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.

chmod

Change mode of a file.

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.

ctime

Return the system time.

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.

date

Return the date.

Synopsis

character*(*) function date(buf)

Description

Returns the ASCII representation of the current date. The form returned is dd-mmm-yy.

error functions

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

etime, dtime

Get the elapsed time.

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.

exit

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.

fdate

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.

fgetc

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.

flush

Flush a logical unit.

Synopsis

subroutine flush(lu)
integer lu

Description

flush flushes the contents of the buffer associated with logical unit lu.

fork

Fork a process.

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.

fputc

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.

free

Free memory.

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.

fseek

Position file at offset.

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 :

0

beginning of the file

1

current position

2

end of the file

ftell

Determine file position.

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.

gerror

Return system error message.

Synopsis

character*(*) function gerror()

Description

Return the system error message of the last detected system error.

getarg

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.

iargc

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.

getc

Get character from unit 5.

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.

getcwd

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.

getenv

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.

getgid

Get group id.

Synopsis

integer function getgid()

Description

Return the group id of the user of the process.

getlog

Get user's login name.

Synopsis

character*(*) function getlog()

Description

getlog returns the user's login name or blanks if the process is running detached from a terminal.

getpid

Get process id.

Synopsis

integer function getpid()

Description

Return the process id of the current process.

getuid

Get user id.

Synopsis

integer function getuid()

Description

Return the user id of the user of the process.

gmtime

Return system time.

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.

hostnm

Get name of current host.

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.

idate

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.

ierrno

Get error number.

Synopsis

integer function ierrno()

Description

Return the number of the last detected system error.

ioinit

Initialize I/O

Synopsis

subroutine ioinit(cctl, bzro, apnd, prefix, vrbose)
integer cctl
integer bzro
integer apnd
character*(*) prefix
integer vrbose

Description

Currently, no action is performed.

isatty

Is logical unit a tty.

Synopsis

logical function isatty(lu)
integer lu

Description

Returns .TRUE. if logical unit lu is connected to a terminal; otherwise, .FALSE. is returned.

itime

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.

kill

Send signal to a process.

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.

link

Make link

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.

lnblnk

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.

loc

Address of an object.

Synopsis

integer function loc(a)
integer a

Description

Return the value which is the address of a.

ltime

Return system time.

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.

malloc

Allocate memory.

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.

mclock

Get elapsed time.

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.

mvbits

Move bits.

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.

outstr

Print a character string.

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.

perror

Print error message.

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.

putc

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.

putenv

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.

qsort

Quick sort.

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:

negative

if arg1 is considered to precede arg2

zero

if arg1 is equivalent to arg2

positive

if arg1 is considered to follow arg2

rand, irand, srand

Random number generator.

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.

random, irandm, drandm

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

range

Range functions.

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

flmin

minimum single precision value

flmax

maximum single precision value

ffrac

smallest positive single precision value

dflmin

minimum double precision value

dflmax

maximum double precision value

dffrac

smallest positive double precision value

inmax

maximum integer

rename

Rename a file.

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.

rindex

Return index of substring.

Synopsis

integer function rindex(a1, a2)
character*(*) a1
character*(*) a2

Description

Return the index of the last occurrence of string a2 in string a1.

secnds, dsecnds

Return elapsed time.

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.

signal

Signal facility.

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.

sleep

Suspend execution for a period of time.

Synopsis

subroutine sleep(itime)
integer itime

Description

Suspends the process for t seconds.

stat, lstat, fstat

Get file status.

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.

stime

Set time.

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.

symlnk

Make symbolic link.

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.

system

Issue a shell command.

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.

time

Return system time.

Synopsis

integer function time()

Description

Return the time since 00:00:00 GMT, January 1, 1970, measured in seconds.

times

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.

ttynam

Get name of a terminal

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.

unlink

Remove a file.

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

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.

<< " border=0>