\input texinfo.tex
@c %**start of header
@setfilename g77-rtl.info
@settitle GNU Fortran Library
@c %**end of header

@iftex
@finalout
@c DL: lose the egregious vertical whitespace, esp. around examples
@c but paras in @defun-like things don't have parindent, so don't set
@c this to 0pt plus...
@parskip 4pt plus 1pt
@end iftex

@set unix In the @samp{unix} intrinsics set.

@ifinfo
This file documents the user-callable routines in the GNU Fortran
runtime library for g77 version 0.5.18.
@end ifinfo

@titlepage
@sp 10
@center @titlefont{User-callable Routines in the GNU Fortran}
@vskip 5pt
@center @titlefont{Runtime Library}
@sp 2
@center for @code{g77} version 0.5.18
@sp 4
@center Dave Love @code{<d.love@@dl.ac.uk>}
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995, 1996 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Copying'' and ``GNU General Public License'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.

@end titlepage

@node Top, Copying, (dir), (dir)

@ifinfo
This file documents the user-callable routines in the GNU Fortran
runtime library for g77 version 0.5.18.
@end ifinfo

@menu
* Copying::                     Copyright statement
* Introduction::                
* Command line and exiting::    
* Date and times::              
* Numerical routines::          
* Files and directories::       
* Errors::                      
* Process Information::         
* I/O::                         
* Miscellaneous::               
* Concept index::               
* Procedure index::             
@end menu


@ifinfo
@node Copying, Introduction, Top, Top
@chapter Copying

Copyright @copyright{} 1995, 1996 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Copying'' and ``GNU General Public License'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end ifinfo

@node Introduction, Command line and exiting, Copying, Top
@chapter Introduction

This manual provides minimal documentation for the user-callable
@code{internal} and @code{external} routines in the GNU Fortran runtime
library.  Mostly these routines are just interfaces to POSIX or
``traditional Unix'' ones expected to be found in the system's C
library.  Thus their semantics are explained in the C library
documentation, referenced as @var{foo}@code{(@var{n})} in @code{man}
page style; if you are using the GNU C library, consult the appropriate
@code{info} nodes.  In some cases, where the C library (or the operating
system) is deficient, routines may not actually be present in the GNU
Fortran library.  Additionally, not all the routines available in even
the ``traditional'' collection have yet been implemented.

Beware that routines of these names are not implemented consistently
across Unix (and other) Fortran compilers and they are not all yet
intrinsics in GNU Fortran---the calling sequences may change when they
are, due to @code{g77}'s conventions that functions should be
side-effect-free.  These versions mostly follow those from the SunPro
Fortran compiler for SunOS@.  They are traditionally found in
@code{libU77} on BSD systems.  In some cases, where VMS Fortran has a
different calling sequence from the normal Unix variants, there is a
version of routine @var{foo} called @code{vxt}@var{foo} with the VMS
calling sequence.  Some VMS Fortran intrinsics are implemented here which
are not normally in libU77, such as @code{secnds}.  Also, a few
Fortran90 intrinsics are included.

The routines @code{abort}, @code{erf}, @code{derf}, @code{erfc},
@code{derfc}, @code{exit}, @code{flush}, @code{fseek}, @code{ftell},
@code{getarg}, @code{getenv}, @code{iargc}, @code{signal} and
@code{system} come from @code{f2c}'s @code{libF77} library, written at
ATT and maintained by David Gay.

@c @node  Layout conventions,  , Introduction, Introduction
@section Layout conventions
@cindex conventions for layout
@cindex layout conventions

The support in the @TeX{}info package used to format this document isn't
ideal for documenting a Fortran library---it was designed for use with
C and Lisp.  The following layout is used.

For each routine documented, there is a line with the routine name
followed by variable names representing its argument list (if any) and
then a right-justified description of the sort of routine, including its
return type (where appropriate).  Arguments enclosed in `[]' may be
omitted.  The sort may be `Subroutine', `Intrinsic integer function'
etc.  Following that, the types of the arguments are given and then a
description of the routine.  Sometimes two or more related routines are
documented together for convenience, with a line for each routine at the
start of the documentation, followed by the arguments' types.  Argument
types are given in Fortran90 style to include their @samp{intent}
(@samp{in}, @samp{out} or @samp{inout}).

@node Command line and exiting, Date and times, Introduction, Top
@chapter Command line and exiting

@deffn {Intrinsic subroutine} getarg n value
@example
integer, intent(in):: @var{n}
character*(*), intent(out)::  @var{value} 
@end example

@cindex command line arguments
Sets @var{value} to the @var{n}-th command-line argument (or to all
blanks if there are fewer than @var{n} command-line arguments);
@code{call getarg(0,@var{value})} sets @var{value} to the name of the
program (on systems that support this feature).  See @code{iargc} below.
@value{unix}
@end deffn

@deffn {Intrinsic subroutine} abort

Prints a message and potentially causes a core dump via @code{abort(3)}.
@value{unix}
@end deffn

@deffn {Intrinsic subroutine} exit [i]
@example
integer, intent(in):: @var{i}
@end example

Exit the program with status @var{i} after closing open Fortran i/o
units and otherwise behaving as @code{exit(2)}.  If @var{i} is omitted,
the canonical `success' value will be returned to the system.
@value{unix}
@end deffn

@deffn {Intrinsic integer function} iargc ()

@cindex command line arguments
Returns the number of command-line arguments.  @value{unix}
@end deffn

@node Date and times, Numerical routines, Command line and exiting, Top
@chapter Date and times

@deffn {Character*24 function} ctime stime
@example
integer, intent(in):: @var{stime}
@end example

Converts @var{stime}, a system time value, such as returned by
@code{time} to a character string of the form @samp{Sat Aug 19 18:13:14
1995}.  See @samp{ctime(3)}.
@end deffn

@deffn Subroutine date
@example
character, intent(out):: @var{buf}
@end example

Returns a string of the form @samp{@var{dd}-@var{mmm}-@var{yy}},
representing the numeric day of the month @var{dd}, a three-character
abbreviation of the month name @var{mmm} and the last two digits of the
year @var{yy}, e.g.@ @samp{25-Nov-96}.
@end deffn

@deffn {Real function} dtime tarray
@deffnx {Real function} etime tarray
@example
real, intent(out):: @var{tarray}(2)
@end example

Return the runtime in seconds of the calling process as the function
value and the user and system components of this in @code{tarray(1)} and
@code{tarray(2)} respectively.  The functions' value is equal to
@code{tarray(1) + tarray(2)}.  @code{etime} and the first call of
@code{dtime} return times since the start of the process' execution;
subsequent calls of @code{dtime} return values since the last time it
was called.
@end deffn

@deffn {Character*24 function} fdate

Returns the date in the same format as @code{ctime}, i.e.@:
@example
  ftime () @equiv{} ctime (time ())
@end example
@end deffn

@deffn Subroutine gmtime stime tarray
@deffnx Subroutine ltime stime tarray
@example
integer, intent(in):: @var{stime}
integer, intent(out):: @var{tarray}(9)
@end example

Given a system time value @var{stime}, fills @var{tarray} with values
extracted from it, either for local time (@code{ltime}) or the GMT
timezone (@code{gmtime}) using @samp{ltime(3)} and @samp{gmtime(3)}
respectively.  The array elements are as follows:
@enumerate
@item
Seconds after the minute, range 0--59 or 0--61 to allow for leap
seconds;
@item
Minutes after the hour, range 0--59;
@item
Hours past midnight, range 0--23;
@item
Day of month, range 0--31;
@item
Number of months since January, range 0--12;
@item
Number of days since Sunday, range 0--6;
@item
Years since 1900;
@item
Days since January 1;
@item
Daylight savings indicator: positive if daylight saving is in effect,
zero if not, and negative if the informtion isn't available.
@end enumerate
See @samp{gmtime(3)}, @samp{localtime(1)}.
@end deffn

@deffn Subroutine idate tarray
@example
integer, intent(out):: @var{tarray}(3)
@end example

Fills @var{tarray} with the numerical values of the current local time
day, month (in the range 1--12) and year.  The year has four significant
digits.
@end deffn

@deffn Subroutine itime tarray
@example
integer, intent(out):: @var{tarray}(3)
@end example

Returns the current local time hour, minute and second in elements of
@var{tarray} in that order.
@end deffn

@deffn {Integer function} mclock

Returns the number of clock ticks since the start of the process.  Only
defined on systems with @samp{clock(3)} (q.v.).
@end deffn

@deffn {Real function} secnds t
@example
real, intent(in):: @var{t}
@end example

Returns (as a real number) the local time in seconds since midnight
minus the value @var{t}.  This is a VMS Fortran intrinsic.
@end deffn

@deffn {Real function} second

Returns the process' runtime in seconds---the same as @code{etime}
returns.  This routine is known from Cray Fortran.
@end deffn

@deffn Subroutine system_clock count count_rate count_max
@example
integer, intent(out):: @var{count}, @var{count_rate}, @var{count_max}
@end example

Implements a version of the Fortran90 intrinsic (not normally in
libU77)@.  @var{count} returns the current value of the system clock;
this is the value returned by @samp{times(2)} here, but isn't in
general.  @var{count_rate} is the number of clock ticks per second and
@var{count_max} is the maximum value this can take, which isn't very
useful in this implementation since it's just the maximum C
@code{unsigned int} value.
@end deffn

@deffn {Integer function} time
Returns the current time encoded as an integer in the manner of
@samp{time(3)}.  This value is suitable for passing to @code{ctime},
@code{gmtime} and @code{ltime}.
@end deffn

@node Numerical routines, Files and directories, Date and times, Top
@chapter Numerical routines

@deffn {Real function} besj0 x
@deffnx {Real function} besj1 x
@deffnx {Real function} besjn n x
@example
real, intent(in):: @var{x}
integer, intent(in):: n
@end example

@cindex Bessel functions
@code{besj0} and @code{besj1} return the Bessel function of @var{x} of
the first kind of orders 0 and 1 respectively.  @code{besjn} is similar,
for order @var{n}.  See @samp{bessel(3m)}, on whose implementation
Bessel functions and the ones described below depend.  @value{unix}
@end deffn

@deffn {Real function} besy0 x
@deffnx {Real function} besy1 x
@deffnx {Real function} besyn n x
@example
real, intent(in):: @var{x}
integer, intent(in):: n
@end example

@cindex Bessel functions
@code{besy0} and @code{besy1} return the Bessel function of @var{x} of
the second kind of orders 0 and 1 respectively.  @code{besyn} is similar,
for order @var{n}.  @var{x} must be positive.  @value{unix}
@end deffn

@deffn {Double Precision function} besj0 x
@deffnx {Double Precision function} besj1 x
@deffnx {Double Precision function} besjn n x
@deffnx {Double Precision function} besy0 x
@deffnx {Double Precision function} besy1 x
@deffnx {Double Precision function} besyn n x
@example
double precision, intent(in):: @var{x}
integer, intent(in):: @var{n}
@end example

@cindex Bessel functions
These are double precision versions of their real counterparts described
above.  @value{unix}
@end deffn

@deffn {Intrinsic real function} erf r
@deffnx {Intrinsic double precision function} derf d
@example
real, intent(in):: @var{r}
double precision, intent(in):: @var{d}
@end example

@cindex error function
The real and double precision error functions respectively.  See
@samp{erf(3m)}, on which these depend.  @value{unix}
@end deffn

@deffn {Intrinsic real function} erfc r
@deffnx {Intrinsic double precision function} derfc d
@example
real, intent(in):: @var{r}
double precision, intent(in):: @var{d}
@end example

The real and double precision complementary error functions
respectively: @code{erfc(r) = 1 - erf(r)} and @code{derfc(d) = 1.d0 -
derfc(d)} (except that their results may be more accurate than
explicitly evaluating the above formulae would give). See
@samp{erfc(3M)}, on which these depend.  @value{unix}
@end deffn

@deffn {Integer function} irand flag
@deffnx {Real function} rand flag
@deffnx {Subroutine} srand seed
@example
integer, intent(in):: @var{flag}, @var{seed}
@end example

@cindex random numbers
@code{irand} returns a uniform quasi-random number up to a
system-dependent limit.  If @var{flag} is 0, the next number in sequence
is returned; if @var{flag} is 1 the generator is restarted by calling
@code{srand(0)}; if @var{flag} has any other value it is used as a new
seed with @code{srand}.  @code{rand} is similar, but returns a real
number between 0 and 1.  @code{srand} reinitialises the generator with
the given @var{seed}.  See @samp{rand(3)}, @samp{srand(3)}.

@emph{Note that as typically implemented, this random number generator
is a very poor one.}  You almost certainly want to use something better.
@end deffn

@node Files and directories, Errors, Numerical routines, Top
@chapter Files and directories

@deffn {Integer function} access name mode
@example
character*(*), intent(in):: @var{name}, @var{mode}
@end example

Checks file @var{name} for accessibility in the given @var{mode} and
returns 0 if the file is accessible in that mode, otherwise an error code
if the file is inaccessible or @var{mode} is invalid.  See
@samp{access(2)}.  @var{mode} may be a concatenation of the characters
@table @samp
@item r
read permission
@item w
Write permission
@item x
executability
@item @var{blank}
existence
@end table
@end deffn

@deffn {Integer function} chdir name
@example
character*(*), intent(in):: @var{name}
@end example

Sets the current working directory to be @var{name}.  Returns 0 on
success or an error code otherwise.  See @samp{chdir(3)}.
@end deffn

@deffn {Integer function} chmod name mode
@example
character*(*), intent(in):: @var{name}, @var{mode}
@end example

Changes the access mode of file @var{name} according to the
specification @var{mode}, which is given in the format of
@samp{chmod(1)}.  Returns 0 on success, and error code otherwise.  Note
that this currently works by actually invoking @code{/bin/chmod} (or the
@code{chmod} found when the library was configured) and so may fail in
some circumstances.
@end deffn

@deffn {Integer function} getcwd name
@example
character*(*), intent(out):: @var{name}
@end example

Places the current working directory in @var{name}.  Returns 0 on
success, otherwise an error number.
@end deffn

@deffn {Integer function} fstat unit sarray
@deffnx {Integer function} sstat file sarray
@deffnx {Integer function} lstat file sarray
@example
integer, intent(in):: @var{unit}
integer, intent(out):: @var{sarray}(13)
character*(*), intent(in):: @var{file}
@end example

@code{fstat} obtains data about the file open on Fortran i/o unit
@var{unit} and places them in the array @var{sarray}.  The values in
this array are extracted from the @code{stat} structure as returned by
@samp{fstat(2)} q.v., as follows:
@enumerate
@item
File mode;
@item
Inode number;
@item
ID of device containing directory entry for file;
@item
Device id (if relevant);
@item
Number of links;
@item
Owner's uid;
@item
Owner's gid;
@item
File size (bytes);
@item
Last access time;
@item
Last modification time;
@item
Last file status change time;
@item
Preferred i/o block size;
@item
Number of blocks allocated.
@end enumerate
Not all these elements are relevant on some systems, in which case they
are returned as 0.

@code{stat} is similar, except that it returns data on the named
@var{file}.  @code{lstat} is like @code{stat} except that if @var{file}
is a symbolic link it returns data on the link itself; it is only
available on systems which support symbolic links.

The routines return 0 on success, otherwise an error number.
@end deffn

@deffn {Integer function} link path1 path2
@deffnx {Integer function} symlnk path1 path2
@example
character*(*), intent(in):: @var{path1}, @var{path2}
@end example

@code{link} makes a (hard) link from @var{path1} to @var{path2}.
Returns 0 on success, an error code otherwise.  See @samp{link(2)}.
@code{symlnk} is similar, but makes a symbolic link; it is only
available on systems which support symbolic links (see
@samp{symlink(2)}).
@end deffn

@deffn {Integer function} rename path1 path2
@example
character*(*), intent(in):: @var{path1}, @var{path2}
@end example

Renames the file @var{path1} to @var{path2}.  See @samp{rename(2)}.
@end deffn

@deffn {Integer function} umask mask
@example
integer, intent(in):: @var{mask}
@end example

Sets the file creation mask to @var{mask} and returns the old value.
See @samp{umask(2)}.
@end deffn

@deffn {Integer function} unlink path
@example
character*(*), intent(in):: @var{path}
@end example

Unlink the file @var{path}.  See @samp{unlink(2)}.
@end deffn

@node Errors, Process Information, Files and directories, Top
@chapter Errors

@deffn Subroutine gerror message
@example
character(*), intent(out):: @var{message}
@end example

Returns the system error message corresponding to the last system error
(C @code{errno}).
@end deffn

@deffn {Integer function} ierrno

Returns the last system error number (corresponding to the C
@code{errno}).
@end deffn

@deffn Subroutine perror str
@example
character*(*), intent(in):: @var{str}
@end example

Prints (on the C @code{stderr} stream) a newline-terminated error
message corresponding to the last system error.  This is prefixed by
@var{str}, a colon and a space.  See @samp{perror(3)}.
@end deffn

@node Process Information, I/O, Errors, Top
@chapter Process Information

@deffn {Integer function} getgid
@deffnx {Integer function} getuid
@deffnx {Integer function} getpid

@code{getgid}, @code{getuid} and @code{getpid} return the group, user
and process ids for the current process.
@end deffn

@deffn {Intrinsic subroutine} getenv name value
@example
character*(*), intent(in):: @var{name}
character*(*), intent(out):: @var{value}
@end example

Sets @var{value} to the value of environment variable @var{name}
(@code{$name} in shell terms), or to blanks if @code{$name} has not been
set.  @value{unix}
@end deffn

@deffn {Subroutine} getlog name
@example
character*(*), intent(out):: @var{name}
@end example

Returns the login name for the process in @var{name}.
@end deffn

@deffn {Integer function} hostnm name
@example
character*(*), intent(out):: @var{name}
@end example

Fills @var{name} with the system's host name returned by
@samp{gethostname(2)}.  This function is not be available on all
systems.
@end deffn

@node I/O, Miscellaneous, Process Information, Top
@chapter I/O

@deffn {Integer function} fgetc @var{unit} @var{c}
@deffnx {Integer function} fget @var{c}
@deffnx {Integer function} fputc @var{unit} @var{c}
@deffnx {Integer function} fput @var{c}
@example
integer, intent(in):: @var{unit}
character, intent(out):: @var{c}
@end example

@cindex stream i/o
@samp{fgetc} reads into @var{c} the next character from the file
(stream) connected to the open Fortran i/o @var{unit} using
@samp{fgetc(3)}, bypassing normal i/o processing.  Newline characters
will be returned literally.  @samp{fget} is similar except that it
always uses unit 5.

@samp{fputc} writes @var{c} to the file (stream) connected to the open
Fortran i/o @var{unit} using @samp{fputc(3)}, bypassing normal i/o
processing.  @samp{fput} is similar except that it always uses unit 6.
A somewhat less efficient version of @samp{fputc} can be written using
normal i/o and the @samp{$} format specifier.

These routines return zero on success, otherwise a system error number
or @minus{}1 for end-of-file.

It is probably unwise to mix such stream-based i/o with normal
record-based i/o on the same unit.  Anyway, you must obey the C rules
concerning standard i/o, not switching between reading and writing
without an intervening seek etc.  In fact it seems to be necessary
actually to @samp{close} and re-@samp{open} the unit if you @samp{fputc}
to it and subsequently want to @samp{fgetc}; this shouldn't be the case.
@end deffn

@deffn {Intrinsic subroutine} flush [@var{unit}]
@example
integer, intent(in):: @var{unit}
@end example

Flushes all the units currently open for output.  The optional argument
is ignored since the runtime library currently contains no facility for
flushing individual units.  @value{unix}
@end deffn

@deffn {Integer function} fnum unit
@example
integer, intent(in):: @var{unit}
@end example

Returns the Unix file descriptor number corresponding to the open Fortran i/o
@var{unit}.  This could be passed to an interface to C i/o routines.
@end deffn

@deffn {Intrinsic subroutine} fseek @var{unit} @var{offset} @var{whence} *@var{errlab}
@example
integer, intent(in):: @var{unit}, @var{offset}, @var{whence}
@end example

@cindex stream i/o
Attempts to move Fortran unit @var{unit} to the specified @var{offset}:
absolute offset if @var{whence}=0; relative to the current offset if
@var{whence}=1; relative to the end of the file if @var{whence}=2.  It
branches to label @var{errlab} if @var{unit} is not open or if the call
otherwise fails.  @value{unix}
@end deffn

@deffn {Integer function} ftell @var{unit}
@example
integer, intent(in):: @var{unit}
@end example

@cindex stream i/o
Returns the current offset of Fortran unit @var{unit} (or -1 if
@var{unit} is not open).  @value{unix}
@end deffn

@deffn {Logical function} isatty unit
@example
integer, intent(in):: @var{unit}
@end example

Returns @code{.true.} iff the Fortran i/o unit is connected to a
terminal device.  See @samp{isatty(3)}.
@end deffn

@deffn {Character*(*) function} ttynam unit
@example
integer, intent(in):: @var{unit}
@end example

Returns the name of the terminal device open on logical unit @var{unit}
or a blank string if @var{unit} is not connected to a terminal.
@end deffn

@node Miscellaneous, Concept index, I/O, Top
@chapter Miscellaneous

@deffn {Intrinsic subroutine} signal n func
@example
integer, intent(in):: @var{n}
external @var{func}
@end example

Arranges for @var{func} to be invoked when signal @var{n} occurs.  This
is of limited use since @var{func} is called with C conventions.
@value{unix}
@end deffn

@deffn {Integer function} kill pid signal
@example
integer, intent(in):: @var{pid}, @var{signal}
@end example

Sends the given @var{signal} to the process @var{pid}.  Returns zero on
success, otherwise an error number.  See @samp{kill(2)}.
@end deffn

@deffn {Integer function} lnblnk str
@deffnx {Integer function} len_trim str
@example
character*(*), intent(in):: @var{str}
@end example

Returns the index of the last non-blank character in @var{str}.
@code{len_trim} is the name of the Fortran90 intrinsic with is function.
@end deffn

@deffn Subroutine sleep t
@example
integer, intent(in):: @var{t}
@end example

Causes the process to pause for @var{t} seconds.  See @samp{sleep(2)}.
@end deffn

@deffn {Intrinsic subroutine} system cmd [ret]
@example
character, intent(in):: @var{cmd}
integer, intent(out):: @var{ret}
@end example

Passes @var{cmd} to a shell (see @code{system(3}).  If argument
@var{ret} is present, it contains the value returned by
@code{system(3)}.  @value{unix}
@end deffn

@node Concept index, Procedure index, Miscellaneous, Top
@unnumbered Concept index
@printindex cp

@node Procedure index,  , Concept index, Top
@unnumbered Procedure index
@printindex fn
@contents
@bye
