avram/doc/avram.1

.\"                              hey, Emacs:   -*- nroff -*-
.\" avram is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; see the file COPYING.  If not, write to
.\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.TH AVRAM 1 "January 31, 2007"
.\" Please update the above date whenever this man page is modified.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins (default)
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
avram \- Applicative ViRtuAl Machine
.SH SYNOPSIS
.nf
\fBavram\fP [general options]
.br
\fBavram\fP [filter mode options] codefile[.avm] < inputfile
.br
\fBavram\fP [parameter mode options] codefile[.avm] [parameters]
.fi
.SH DESCRIPTION
\fBavram\fP is a virtual machine code interpreter. It reads an input
file containing an application written in virtual machine code, and
executes it on the host machine. The virtual machine code normally will
have been translated from a high level language by a compiler, allowing
\fBavram\fP to be independent of the source language.
.PP
In theory, virtual machine programs are more easily
portable than those in native code because they run without
modification on any platform to which the interpreter has been
ported. Virtual machines may also simplify the job of a compiler
writer by providing more direct support for high level language
features than is possible or appropriate for real hardware.
.PP
The virtual code format used by \fBavram\fP is designed to
support the features of functional or applicative programming
languages. This manpage documents only the usage of \fBavram\fP
and not the internals, but it will be helpful in what follows to keep
in mind that the virtual machine code expresses a mathematical
function rather than a program in the conventional sense. As such, it
performs no action directly, but may be applied in a choice of ways by
the user of \fBavram\fP according to the precise operation required.
.SH GENERAL OPTIONS

Regardless of whatever other command line parameters are given,
\fBavram\fP accepts the following parameters:
.TP
.B -h, --help
Show a summary of options and exit.
.TP
.B -V,-v, --version
Show the version of program and a short copyleft message and exit.
.TP
.B --emulation=\fIversion\fP
Be backward compatible with an older version of \fBavram\fP.  This
option should include a valid version number, for example
0.1.0, which is the version of \fBavram\fP to be
emulated. It can make virtual code applications future proof, assuming
that future versions of \fBavram\fP correctly support backward
compatibility. It may be used in conjunction with any other option in
any mode of operation.

This copy of the manpage has not been updated since version 0.7.0 of
\fBavram\fP, so it is unable to document incompatibilities with later
versions. The latest version of the manual may be found at
\fBhttp://www.basis.uklinux.net/avram\fP.
.TP
.B -e, --external-libraries
Show a list of libraries with which \fBavram\fP has been linked and
whose functions therefore could be called from virtual machine
programs. This growing list currently includes selected functions from
fftw, glpk, gsl, lapack, minpack, mpfr, pcx, rmath, umf, and
kinsol which are documented further in the \fBavram\fP reference manual.
.TP
.B -j, --jail
This option disables execution of shell commands by virtual code
applications, which is normally possible by default even for nominally
non-interactive applications (see below). A virtual code application
attempting to spawn a shell (using the interact combinator) when this
option is selected will encounter an exception rather than successful
completion of the operation. This option is provided as a security
feature for running untrusted code, and is incompatible with \fB-i\fP,
\fB-t\fP, and \fB-s\fP.
.TP
.B -f, --force-text-input
Normally \fBavram\fP will try to guess by looking at a file whether it
is an ordinary text file or one that has been written in the virtual
code file format, and choose a different internal representation
accordingly. An application may require one representation or the
other. This option tells \fBavram\fP to treat all input files other
than the virtual code file as text files regardless of whether or not it
would be possible to interpret them otherwise. This option may be used
in combination with any other option.
.SH MODES OF OPERATION
Apart from to the capability to print brief help messages and exit,
there are two main modes of operation, depending on which options
are specified.
.TP
.B Filter mode
In filter mode, the argument to the function given by the virtual code
is taken from standard input, and the result is written to standard
output, except for error messages resulting from a failure to evaluate
the function, which are written to standard error. Filter mode is
indicated whenever these three conditions are all met.
.RS
.TP
*
Either at least one of the filter mode options listed below appears
on the command line preceding the first filename parameter, or there
are no options at all.
.TP
*
Exactly one filename parameter appears on the command line,
which is the name of the virtual machine code file.
.TP
*
Either the filename comes last on the command line, or the
\fB--unparameterized\fP option precedes it, causing
everything following it to be ignored.
.RE
.TP
.B Parameter mode
In parameter mode, the argument to the function given by the virtual
code is a data structure containing environment variables and command
line parameters including files, application specific options, and
possibly standard input. The result obtained by evaluating the
function is either a data structure representing a set of files to be
written, which may include standard output, or a sequence of shell
commands to be executed, or a combination of both. Parameter mode is
indicated whenever either of these conditions is met.
.RS
.TP
*
Any of the parameter mode options listed below appears on the
command line preceding the first filename parameter.
.TP
*
At least one additional filename parameter or option follows the first one,
and the \fB--unparameterized\fP option is not selected.
.RE
.P
For the purpose of choosing the mode of operation, the virtual
code filename is taken to be the first command line argument not
beginning with a dash. Other conventions relevant to application
specific parameters are detailed below.
.SH FILTER MODE OPTIONS
The options available in filter mode are listed below. Except as
otherwise noted, all options are mutually exclusive. Ordinarily a
given application will require certain fixed settings of these options
and will not work properly if they are set inappropriately.
.TP
.B -r, --raw-output
Normally the result obtained by evaluating the function in the virtual
code file must be a list of character strings, which is written as
such to standard output. However, if this option is selected, the form
of the result is unconstrained, and it will be written in a data file
format that is not human readable but can be used by other
applications. This option is incompatible with any other options
except \fB-u\fP.
.TP
.B -c, --choice-of-output
When this option is used, the evaluation of the function given by the
virtual machine code will be expected to yield a data structure from
which \fBavram\fP will ascertain whether standard output should be
written in text or raw data format.  This option should be used only
if application is aware of it. It is incompatible with any other options
except \fB-u\fP.
.TP
.B -l, --line-map
Normally the entire contents of standard input up to EOF are loaded
into memory and used as the argument to the function in the virtual
code file. However, this option causes standard input to be read a
line at a time, with the function applied individually to each line in
sequence, and its result in each case written to standard output as
soon as it is computed. A given application either requires this
option or does not, and will not work properly in the
alternative. This option implies \fB-f\fP and is incompatible with any
other option except \fB-u\fP.
.TP
.B -b, --byte-transducer
This option causes standard input to be read one character at a time,
evaluating the function given by the virtual code file each time. The
function is used as a state transition function that takes a state and
input to a next state and output. The output is expected to be a
character string and is written concurrently with the input
operations. A given application will not work properly with an
inappropriate setting of this option.  This option implies \fB-f\fP
and is incompatible with any other option except \fB-u\fP.
.TP
.B -u, --unparameterized
Normally \fBavram\fP guesses whether to use filter mode or parameter
mode depending on whether there are any parameters. Selecting this
option forces it to operate in filter mode regardless. Any parameters
that may appear on the command line after the virtual code file name
are ignored. This option may be used in conjunction with any other
filter mode option.
.SH PARAMETER MODE OPTIONS
The parameter mode options are listed below. Except as otherwise
noted, any combination of parameter mode options may be selected
together, and except as noted, the settings of these options can be
varied without breaking the application.
.TP
.B -q, --quiet
\fBavram\fP normally informs the user when writing an output file with
a short message to standard output. This option suppresses such
messages. This option is compatible with any application and any other
parameter mode option except \fB-a\fP.
.TP
.B -a, --ask-to-overwrite
Selecting this option will cause \fBavram\fP to ask permission
interactively before overwriting an existing file, and to refrain from
overwriting it without permission, in which case the contents that
were to be written will be lost. This option overrides \fB-q\fP and is
compatible with any other parameter mode option or application.
.TP
.B -.EXT
An option beginning with a dash followed by a period specifies a
default extension for input file names. If \fBavram\fP doesn't find a
file named on the command line, and the filename doesn't already
contain a period, \fBavram\fP will try to find a file having a similar
name but with the default extension appended. The default extension given
by this option takes precedence over the hard coded default extensions
of .fun and .avm. At most one default extension can be supplied. This
option is compatible with any other parameter mode option and
compatible with any application.
.TP
.B -d, --default-to-stdin
If no filename parameter appears on the command line (other than the
name of the virtual code file), this option directs \fBavram\fP to
read the contents of standard input as if it were specified as a
command line parameter. (Standard input can also be specified
explicitly as a dash.) This option is compatible with any application
and any other parameter mode option except \fB-m\fP.
.TP
.B -m, --map-to-each-file
Normally \fBavram\fP loads the entire contents of all files named on
the command line into memory so as to evaluate the virtual machine
code application on all of them together. This option can be used to
save memory in the case of applications that operate on multiple files
independently. It causes \fBavram\fP to load only one file at a time
and to perform the relevant evaluation and output before loading the
next one. Application specific options and standard input (if
specified) are read only once and reused. This option is incompatible
with \fB-d\fP, and not necessarily compatible with all applications,
although some may work both with and without it.
.TP
.B -i, --interactive
This option is used in the case of applications that interact with
other programs through shell commands. An application that is meant to
be invoked in this way requires this option and will not work without
it, nor will applications that are not of this type work with it. This
option is implied by \fB-t\fP and \fB-s\fP, and is compatible with any
other parameter mode option.

.TP
.B -s, --step
This option is used in the case of applications that interact with
other programs through shell commands, similarly to \fB-i\fP, and can
substitute for it (see above). The option has the additional effect of
causing shell commands issued by \fBavram\fP on behalf of the
application to be written with their results to standard output, and
to cause \fBavram\fP to pause after displaying each shell command
until a key is pressed.  This capability may be useful for debugging
or auditing purposes but does not otherwise alter the effects of the
application.  This option is compatible with any other parameter mode
option.
.TP
.B -t, --trace
This option is used in the case of applications that interact with
other programs through shell commands, but only by way of the
\fBinteract\fP combinator, for which it provides developers a means
of low level debugging, particularly deadlock detection. When this
option is selected, a verbose trace of all characters exchanged
between the functional transducer and the external application are
written to standard output, along with some additional control flow
diagnostics. This option is compatible with any other parameter mode
option.
.TP
.B -p, --parameterized
Normally \fBavram\fP tries to guess whether to operate in filter mode
or parameter mode based on the options used and the parameters. If
there are no parameters and no options, it will default to filter
mode, and try to read standard input. However, if this option is
selected, it will use parameter mode (and therefore not try to read
standard input unless required).
.SH COMMAND LINE SYNTAX
The command line parameters that follow the virtual code file name
when \fBavram\fP is used in parameter mode are dependent on the
specific application. However, all supported applications are
constrained for implementation reasons to observe certain uniform
conventions regarding their command line parameters, which are
documented here to avoid needless duplication.
.P
The shell divides the command line into "arguments" separated by white
space.  Arguments containing white space or special characters used by
the shell must be quoted or protected as usual. File names with wild
cards in them are expanded by the shell before \fBavram\fP sees them.
.P
\fBavram\fP then extracts from the sequence of arguments a sequence of
filenames and a sequence of options. Each option consists of a keyword and an
optional parameter list. Filenames, keywords, and parameter lists are
distinguished according to the following criteria.
.TP
1.
An argument is treated as a keyword iff it meets these three
conditions.
.RS
.TP
(a)
It starts with a dash.
.TP
(b)
It doesn't contain an equals sign.
.TP
(c)
It doesn't consist solely of a dash.
.RE
.TP
2.
An argument is treated as a parameter list iff it meets these four
conditions.
.RS
.TP
(a)
It doesn't begin with a dash.
.TP
(b)
It either begins with an equals sign or doesn't contain one.
.TP
(c)
It immediately follows an argument beginning with a dash, not
containing an equals sign, and not consisting solely of a dash.
.TP
(d)
At least one of the following is true.
.RS
.TP
1)
It doesn't contain a period, tilde, or path separator.
.TP
2)
It contains a comma.
.TP
3)
It can be interpreted as a C formatted floating point number.
.RE
.RE
.TP
3.
An argument is treated as an input file name iff it meets these four
conditions.
.RS
.TP
(a)
It doesn't begin with a dash.
.TP
(b)
It doesn't contain an equals sign.
.TP
(c)
It doesn't contain a comma.
.TP
(d)
At least one of the following is true.
.RS
.TP
1)
It contains a period, tilde, or path separator.
.TP
2)
It doesn't immediately follow an argument beginning with a dash,
not consisting solely of a dash, and not containing an equals sign.
.RE
.RE
.TP
4.
If an argument contains an equals sign but doesn't begin with one, the
part on the left of the first equals sign is treated as a keyword and
the part on the right is treated as a parameter list.
.TP
5.
An argument consisting solely of a dash is taken to represent the standard input file.
.TP
6.
An argument not fitting any of the above classifications is an error.
.P
These conventions are needed for \fBavram\fP to detect input file
names in a general, position independent way, so that it can preload
the files on behalf of the application. Many standard Unix utilities
follow these conventions to a large extent, the exceptions being
those that employ non-filename arguments without distinguishing
syntax, and use positional or other ad hoc methods of command line
interpretation. A drop-in replacement for such an application could
nevertheless be implemented using \fBavram\fP with an appropriate
wrapper script, similar to the approach recommended below, but with
suitable keywords inserted prior to the ambiguous arguments.
.RE
.SH DIAGNOSTICS
The means exists for virtual code applications to have run time error
messages written to standard error on their behalf by
\fBavram\fP. Any error messages not documented here originate with an
application and should be documented by it.

Most error messages originating from \fBavram\fP are prefaced by the
application name (i.e., the name of the file containing the virtual
machine code), but will be prefaced by \fBavram\fP: if the error is
caused by a problem loading this file itself. Error
messages originating from virtual machine code applications are the
responsibility of their respective authors and might not be prefaced
by the application name.

The run time errors not specifically raised by the application can be
classified as internal errors, i/o errors, overflow errors, file
format errors, application programming errors, and configuration related
errors.

Some error messages include a code number. The number identifies
the specific point in the source code where the condition was
detected, for the benefit of the person maintaining it.
.TP
.B internal errors
Internal errors should never occur unless the
\fBavram\fP source code has been carelessly modified. There are two kinds.
.RS
.TP
.B \fIapplication-name\fP: virtual machine internal error (code \fInn\fP)
Most internal errors would be reported by a message of this form
if they were to occur. It indicates that some required invariant was
not maintained. In such cases, the program terminates immediately, and
any results already produced are suspect.
.TP
.B \fIapplication-name\fP: \fInn\fP unreclaimed \fIstruct-names\fP
A message of this form could be printed at the end of an otherwise successful
run. \fBavram\fP maintains a count of the number of units allocated
for various data structures, and checks that they are all reclaimed
eventually as a safeguard against memory leaks. This message indicates
that some memory remains unaccounted for.
.RE

.RS
If a repeatable internal error is discovered, please email a bug
report and a small representative test case to the address below.
.RE
.TP
.B i/o errors
These error messages are prefaced with the name of the
application. A further explanation as to the
reason, obtained from the standard \fBstrerror()\fP utility, is
appended to the messages below if possible.
.RS
.TP
.B \fIapplication-name\fP: can't read \fIfilename\fP
A file was not able to be opened for reading, typically because it was
not found or because the user does not have permission. The file name is
displayed with special characters expanded but without any default
extensions or search paths that may have been tried. If you think a file
exists and should have been found, there may be a problem with your
\fBAVMINPUTS\fP environment variable.
.TP
.B \fIapplication-name\fP: can't write \fIfilename\fP
A file was not able to be opened for writing.
.TP
.B \fIapplication-name\fP: can't write to \fIfilename\fP
A file was successfully opened for writing but became impossible to
write thereafter.
.TP
.B \fIapplication-name\fP: can't spawn \fIcommand\fP
An attempt to execute a shell command on behalf of an interactive
application failed during the \fBexp_popen()\fP library call.
.TP
.B \fIapplication-name\fP: can't close \fIfilename\fP
A call to the standard C procedure \fBfclose()\fP failed due to
unforeseen circmstances. The error is non-fatal but the file should
be checked for missing data.
.RE
.TP
.B overflow errors
These errors are reported by the application name prefacing one of the
following messages, except as noted below.
.RS
.TP
.B \fIapplication-name\fP: counter overflow (code \fInn\fP)
An overflow occurred in an unsigned long integer being used as a reference
counter or something similar. This situation is very unlikely.
.TP
.B \fIapplication-name\fP: memory overflow (code \fInn\fP)
There wasn't enough memory to build an internal data structure. The
most likely cause is an attempt to operate on input
files that are too large. Standard remedies apply.
.RE

.RS
The memory overflow or counter overflow messages can also be reported
without the application name preface or a code number. In these cases,
they arise in the course of evaluating the function given by the
application, rather than by loading the input files.

A counter overflow in this case is possible if the application
attempts to compute the size of a very large, shared structure using
native integer arithmetic.

Memory overflows are possible due to insufficient memory for a valid
purpose, but may also occur due to a non-terminating recursion in the
virtual machine code. To prevent thrashing or other bad effects from
runaway code, \fBulimit\fP is your friend.
.RE
.TP
.B file format errors
Certain application crashes result from an application not adhering
to the required conventions about data and file formats, or because the
application was invoked with inappropriate options (see above). These
are the following.
.RS
.TP
.B \fIapplication-name\fP: invalid text format (code \fInn\fP)
An application that was expected to return a string of characters to
be written to a text file returned data that did not correspond to any
valid character representation.
.TP
.B \fIapplication-name\fP: null character in prompt
An interactive application (invoked rightly or wrongly with \fB-i\fP,
\fB-t\fP, or \fB-s\fP) is required to exchange strings of non-null
characters internally with \fBavram\fP, and used a null.
.TP
.B \fIapplication-name\fP: invalid file name (code \fInn\fP)
The data structure representing a file obtained from an application
has a name consisting of something other than character strings. This
error could be the result of a filter mode application being invoked
in parameter mode.
.TP
.B \fIapplication-name\fP: null character in file name
Similar to the above errors.
.TP
.B \fIapplication-name\fP: bad character in file name
Similar to the above errors.
Slashes, backslashes, and unprintable characters other than spaces are
also prohibited in file names.
.TP
.B \fIapplication-name\fP: invalid output preamble format
According the format used by \fBavram\fP for data files, a data file
may contain an optional text portion, known as the preamble. This
error occurs when a data file obtained from an application can not be
written because the preamble is something other than a list of
character strings.
.TP
.B \fIapplication-name\fP: invalid file specification
This error occurs in situations where the data structure for a file
obtained by evaluating the application is too broken to permit any
more specific diagnosis.
.TP
.B \fBavram\fP: invalid raw file format in \fIapplication-name\fP
The file containing the virtual machine code was not able to be
loaded, because the code was not in a recognizable format.
.RE
.TP
.B application programming errors
A further class of application crashes results from miscellaneous bugs
in the application. These require the application to be debugged and
have no user level explanation or workaround, but are listed here for
reference. These messages are not normally prefaced by the application
name when reported unless the application elects to do so, except for
the \fBinvalid profile identifier\fP message.
.RS
.TP
.B invalid recursion
.TP
.B invalid comparison
.TP
.B invalid deconstruction
.TP
.B invalid transpose
.TP
.B invalid membership
.TP
.B invalid distribution
.TP
.B invalid concatenation
.TP
.B invalid assignment
.TP
.B unrecognized combinator (code \fInn\fP)
.TP
.B \fIapplication-name\fP: invalid profile identifier
.TP
.B unsupported hook
.RE
.TP
.B configuration related errors
The source code distribution of \fBavram\fP incorporates a flexible
configuration script allowing it to be installed on a variety of
platforms. Not all platforms allow support for all features. It is also
anticipated that new features may be added to \fBavram\fP from time to
time. Some problems may therefore occur due to features not being
supported at your site for either of these reasons. The following error
messages are relevant to these situations.
.RS
.TP
.B unsupported hook
If it's not simply due to an application programming error, this
message may be the result of trying to use an application that
requires a newer version of \fBavram\fP than the one installed, even
though applications should avoid this problem by checking the version
number at run time. If this is the reason, the solution would be to
install the latest version.
.TP
.B \fIapplication-name\fP: I need avram linked with \fIfoo\fP, \fIbar\fP and \fIbaz\fP.
A message of the this form indicates that a new installation may be
needed. At this writing (11/11/1), \fBavram\fP may report this message
with respect to \fBlibexpect5.32\fP, \fBtcl8.3\fP, and \fBlibutil\fP
if any of the \fB-i\fP, \fB-t\fP, or \fB-s\fP options is used on a
system where not all of these libraries were detected when \fBavram\fP
was installed from a source distribution.
Because \fBavram\fP is useful even without interactive applications,
these libraries are not considered absolute prerequisites by the
configuration script.
.TP
.B avram: can't emulate version \fIversion\fP
The \fB--emulation=\fP\fIversion\fP option obviously won't work if the
requested version is newer than the installed version, or if it is not
a valid version number. When that happens, this message is printed
instead and \fBavram\fP terminates.
.TP
.B avram: multiple version specifications
The \fB--emulation=\fP\fIversion\fP option can be used at most once
on a command line. This message is printed if it is used more than
once.
.TP
.B avram: unrecognized option: \fIoption-name\fP
may mean that a command line option has been misspelled, or may be another
sign of an obsolete version of \fBavram\fP
.TP
.B \fIapplication-name\fP: warning: search paths not supported
If the \fBargz.h\fP header file was not detected during configuration,
\fBavram\fP will not be able to support search paths in the
\fBAVMINPUTS\fP environment variable. This message is a warning that
the environment variable is being ignored. If the warning is followed
by an I/O error, the latter may be due to a file being in a path that
was not searched for this reason. A workaround is to specify the full
path names of all input files outside the current working directory.
If you don't need search paths, you can get rid of this message by
undefining \fBAVMINPUTS\fP.

.RE
.TP
.B Other Diagnostics and Warnings
.RS
.TP
.B avram: multiple -.EXT options; all but last ignored
This message is written when more than one default extension is given as
a command line parameter.  At most one default extension is allowed. If
more than one is given, only the last one is used. The error is
non-fatal and \fBavram\fP will try to continue. If you need more
than one default extension, consider using the hard coded default
extensions of \fB.fun\fP and \fB.avm\fP, or hacking the shell script
in which the \fBavram\fP command line appears.
.TP
.B  \fIapplication-name\fP: empty operator
This message probably means that the virtual code file is corrupt or
invalid.
.TP
.B usage summary
For any errors in usage not covered by other diagnostics, such as
incompatible combinations of options, \fBavram\fP prints a message to
standard error giving a brief summary of options, similar to the output
from \fBavram --help\fP.
.RE
.SH EXAMPLE
It is recommended that the application developer (or the compiler)
package virtual machine code applications as shell scripts with the
\fBavram\fP command line embedded in them. This style relieves the user
of the need to remember the appropriate virtual machine options for
invoking the application, which are always the same for a given
application, or even to be aware of the virtual machine
at all.
.P
Here is a script that performs a similar operation to the standard
Unix \fBcat\fP utility. (That is, it copies the contents of a file whose
name is given on the command line to standard output, or copies
standard input to standard output if no file name is given.) This
script can be marked executable (with \fBchmod\fP) and run by any user
with the \fBavram\fP executable in his or her path (even if
\fBavram\fP had to be installed in a non-standard directory such as
~/bin).

.nf
   #!/bin/sh
   #\\
   exec avram --default-to-stdin "$0" "$@"
   sKYQNTP\\
.fi

The idea for this script is blatantly lifted from the \fBwish\fP
manpage. The first line of the script invokes a shell to process
what follows. The shell treats the second line as a comment and
ignores it.  Based on the third line, the shell invokes \fBavram\fP
with the indicated option, the script itself as the next argument, and
whatever command line parameters were initially supplied by the user
as the remaining arguments. The rest of the script after
that line is never processed by the shell.
.P
When \fBavram\fP attempts to load the shell script as a virtual
machine code file, which happens as a result of it being executed by
the shell, it treats the first line as a comment and ignores it. It
also treats the second line as a comment, but takes heed of the
trailing backslash, which is interpreted as a comment continuation
character. It therefore also treats the third line as a comment and
ignores it. Starting with the fourth line, it reads the virtual code,
which is in a binary data format encoded with printable characters,
and evaluates it.
.SH FILES
.TP
.B ./profile.txt
This file is written automatically by \fBavram\fP on behalf of
applications that include profile annotations. It lists the number of
invocations for each annotated part of the application, the total
amount of time spent on it (in relative units), the average amount of
time for each invocation, and the percentage of time relative to the
remainder of the application.
.SH ENVIRONMENT
An environment variable \fBAVMINPUTS\fP can be made to store a list of
directories (using the \fBset\fP or \fBexport\fP commands) that
\fBavram\fP will search for input files. The directories should be
separated by colons, similarly to the \fBPATH\fP environment variable.

The search paths in \fBAVMINPUTS\fP apply only to the names of input
files given on the command line when
\fBavram\fP is invoked in parameter mode.  They
do not apply to the name of the virtual code file, which is always
assumed to be either absolute or relative to the current working
directory (this assumption being preferable in the case of a script like
the example shown above).

Starting in the first directory in the list of \fBAVMINPUTS\fP,
\fBavram\fP searches for a file exactly as its name appears on the
command line (subject to the expansion of special characters by the
shell). If it is not found and the name does not contain a
period, but a command line option of \fB-.EXT\fP has been used,
\fBavram\fP will then search for a file with that name combined with
the extension \fB.EXT\fP. If \fB-.EXT\fP has not been used or if no
matching file is found with it, \fBavram\fP tries the extensions of \fB.avm\fP
and \fB.fun\fP in that order, provided the given file name
contained no periods. If no match is found for any of those cases,
\fBavram\fP proceeds to search the next directory in the list obtained
from \fBAVMINPUTS\fP, and so on. It stops searching when the first
match is found. For subsequent input files, the search begins again at
the first directory.

If \fBAVMINPUTS\fP is not defined, input file names are assumed to be
absolute or relative to the current working directory. If it is defined,
the current working directory is not searched for input files unless it
is listed.

If \fBAVMINPUTS\fP is defined, the current working directory is not
searched for input files unless it is listed. If it is empty or not
defined, a default list of search paths is used, currently

.nf
 .:/usr/local/lib/avm:/usr/lib/avm:/lib/avm:/opt/avm:/opt/lib/avm
.fi

These paths are defined in \fBavram.c\fP and can be changed
by recompiling it.
.SH BUGS

There are no known bugs outstanding, except for any that may be
inherent in the external library functions. However, \fBavram\fP has
been used most extensively on GNU/Linux systems, and the prospect
of portability issues with new or lesser used features on other
systems can't be excluded.

Though not observed in practice, it's theoretically possible to blow
the stack by passing enough functions as arguments to library
functions that pass more functions to library functions (e.g., by
using nested calls to the gsl integration functions meant for a single
variable to evaluate a very high dimensional multiple integral). In
all other cases only dynamic heap storage or a constant amount of
stack space is used.  In particular, this issue is *not* relevant to
virtual code applications that don't use external libraries, or that
don't pass functions to them as arguments.

\fBavram\fP is designed to recover gracefully from memory overflows by
always checking for \fBNULL\fP results from \fBmalloc()\fP or
otherwise trapping functions that allocate memory. In the event of an
overflow, it conveys an appropriate error message to the virtual code
application to be handled by the usual exception handling mechanisms.
However, there is currently no way for a virtual code application to
detect in advance whether sufficient memory is available, nor for it
to resume normal operation once an exception occurs. Furthermore, it
has been observed on some systems including Irix and 2.4 series Linux
kernels that the \fBavram\fP process is killed automatically for
attempting to allocate too much memory rather than given the chance to
recover.

Please send bug reports to the address below.
.SH SEE ALSO
.BR cat (1),
.BR libexpect (3), 
.BR wish (1), 
.BR bash_builtins (1), 
.BR ulimit (1), 
.BR strerror (3), 
.BR stdin (3),
.BR stdout (3), 
.BR stderror (3), 
.BR info (1),
.BR pinfo (1), 
.BR chmod (1), 
.BR set (1), 
.BR export (1), 
.BR sh (3).

The full documentation for \fBavram\fP is maintained as a Texinfo
manual. If the \fBinfo\fP and \fBavram\fP programs are properly
installed at your site, the command \fBinfo avram\fP or \fBpinfo
avram\fP should give you access to the complete manual. Debian
GNU/Linux users could have a look under \fB/usr/share/doc/*avram*\fP
for possible html or postscript documentation and examples.
.SH AUTHOR
Dennis Furey <[email protected]>.