AVRAM(1)

NAME
avram - Applicative ViRtuAl Machine

SYNOPSIS
avram [general options]
avram [filter mode options] codefile[.avm] < inputfile
avram [parameter mode options] codefile[.avm] [parameters]

DESCRIPTION
avram 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 avram to be independent of the source language.

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.

The virtual code format used by avram is designed to support the features of functional or applicative programming languages. This manpage documents only the usage of avram 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 avram according to the precise operation required.

GENERAL OPTIONS
Regardless of whatever other command line parameters are given, avram accepts the following parameters:

-h, --help
    Show a summary of options and exit.

-V,-v, --version
    Show the version of program and a short copyleft message and exit.

--emulation=version
    Be backward compatible with an older version of avram. This option should include a valid version number, for example 0.1.0, which is the version of avram to be emulated. It can make virtual code applications future proof, assuming that future versions of avram 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 avram, so it is unable to document incompatibilities with later versions. The latest version of the manual may be found at http://www.basis.uklinux.net/avram.

-e, --external-libraries
    Show a list of libraries with which avram 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 avram reference manual.

-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 -i, -t, and -s.

-f, --force-text-input
    Normally avram 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 avram 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.

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.

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.

    *   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.

    *   Exactly one filename parameter appears on the command line, which is the name of the virtual machine code file.

    *   Either the filename comes last on the command line, or the --unparameterized option precedes it, causing everything following it to be ignored.

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.

    *   Any of the parameter mode options listed below appears on the command line preceding the first filename parameter.

    *   At least one additional filename parameter or option follows the first one, and the --unparameterized option is not selected.

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.

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.

-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 -u.

-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 avram 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 -u.

-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 -f and is incompatible with any other option except -u.

-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 -f and is incompatible with any other option except -u.

-u, --unparameterized
    Normally avram 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.

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.

-q, --quiet
    avram 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 -a.

-a, --ask-to-overwrite
    Selecting this option will cause avram 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 -q and is compatible with any other parameter mode option or application.

-.EXT
    An option beginning with a dash followed by a period specifies a default extension for input file names. If avram doesn't find a file named on the command line, and the filename doesn't already contain a period, avram 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.

-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 avram 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 -m.

-m, --map-to-each-file
    Normally avram 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 avram 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 -d, and not necessarily compatible with all applications, although some may work both with and without it.

-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 -t and -s, and is compatible with any other parameter mode option.

-s, --step
    This option is used in the case of applications that interact with other programs through shell commands, similarly to -i, and can substitute for it (see above). The option has the additional effect of causing shell commands issued by avram on behalf of the application to be written with their results to standard output, and to cause avram 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.

-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 interact 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.

-p, --parameterized
    Normally avram 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).

COMMAND LINE SYNTAX
The command line parameters that follow the virtual code file name when avram 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.

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 avram sees them.

avram 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.

1.  An argument is treated as a keyword iff it meets these three conditions.

    (a) It starts with a dash.

    (b) It doesn't contain an equals sign.

    (c) It doesn't consist solely of a dash.

2.  An argument is treated as a parameter list iff it meets these four conditions.

    (a) It doesn't begin with a dash.

    (b) It either begins with an equals sign or doesn't contain one.

    (c) It immediately follows an argument beginning with a dash, not containing an equals sign, and not consisting solely of a dash.

    (d) At least one of the following is true.

        1)  It doesn't contain a period, tilde, or path separator.

        2)  It contains a comma.

        3)  It can be interpreted as a C formatted floating point number.

3.  An argument is treated as an input file name iff it meets these four conditions.

    (a) It doesn't begin with a dash.

    (b) It doesn't contain an equals sign.

    (c) It doesn't contain a comma.

    (d) At least one of the following is true.

        1)  It contains a period, tilde, or path separator.

        2)  It doesn't immediately follow an argument beginning with a dash, not consisting solely of a dash, and not containing an equals sign.

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.

5.  An argument consisting solely of a dash is taken to represent the standard input file.

6.  An argument not fitting any of the above classifications is an error.

These conventions are needed for avram 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 avram with an appropriate wrapper script, similar to the approach recommended below, but with suitable keywords inserted prior to the ambiguous arguments.

DIAGNOSTICS
The means exists for virtual code applications to have run time error messages written to standard error on their behalf by avram. Any error messages not documented here originate with an application and should be documented by it. Most error messages originating from avram are prefaced by the application name (i.e., the name of the file containing the virtual machine code), but will be prefaced by avram: 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.

internal errors
    Internal errors should never occur unless the avram source code has been carelessly modified. There are two kinds.

    application-name: virtual machine internal error (code nn)
        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.

    application-name: nn unreclaimed struct-names
        A message of this form could be printed at the end of an otherwise successful run. avram 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.
    If a repeatable internal error is discovered, please email a bug report and a small representative test case to the address below.

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 strerror() utility, is appended to the messages below if possible.

    application-name: can't read filename
        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 AVMINPUTS environment variable.

    application-name: can't write filename
        A file was not able to be opened for writing.

    application-name: can't write to filename
        A file was successfully opened for writing but became impossible to write thereafter.

    application-name: can't spawn command
        An attempt to execute a shell command on behalf of an interactive application failed during the exp_popen() library call.

    application-name: can't close filename
        A call to the standard C procedure fclose() failed due to unforeseen circmstances. The error is non-fatal but the file should be checked for missing data.

overflow errors
    These errors are reported by the application name prefacing one of the following messages, except as noted below.

    application-name: counter overflow (code nn)
        An overflow occurred in an unsigned long integer being used as a reference counter or something similar. This situation is very unlikely.

    application-name: memory overflow (code nn)
        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.
    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, ulimit is your friend.

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.

    application-name: invalid text format (code nn)
        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.

    application-name: null character in prompt
        An interactive application (invoked rightly or wrongly with -i, -t, or -s) is required to exchange strings of non-null characters internally with avram, and used a null.

    application-name: invalid file name (code nn)
        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.

    application-name: null character in file name
        Similar to the above errors.

    application-name: bad character in file name
        Similar to the above errors. Slashes, backslashes, and unprintable characters other than spaces are also prohibited in file names.

    application-name: invalid output preamble format
        According the format used by avram 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.

    application-name: 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.

    avram: invalid raw file format in application-name
        The file containing the virtual machine code was not able to be loaded, because the code was not in a recognizable format.

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 invalid profile identifier message.

    invalid recursion

    invalid comparison

    invalid deconstruction

    invalid transpose

    invalid membership

    invalid distribution

    invalid concatenation

    invalid assignment

    unrecognized combinator (code nn)

    application-name: invalid profile identifier

    unsupported hook

configuration related errors
    The source code distribution of avram 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 avram 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.

    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 avram 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.

    application-name: I need avram linked with foo, bar and baz.
        A message of the this form indicates that a new installation may be needed. At this writing (11/11/1), avram may report this message with respect to libexpect5.32, tcl8.3, and libutil if any of the -i, -t, or -s options is used on a system where not all of these libraries were detected when avram was installed from a source distribution. Because avram is useful even without interactive applications, these libraries are not considered absolute prerequisites by the configuration script.

    avram: can't emulate version version
        The --emulation=version 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 avram terminates.

    avram: multiple version specifications
        The --emulation=version option can be used at most once on a command line. This message is printed if it is used more than once.

    avram: unrecognized option: option-name
        may mean that a command line option has been misspelled, or may be another sign of an obsolete version of avram

    application-name: warning: search paths not supported
        If the argz.h header file was not detected during configuration, avram will not be able to support search paths in the AVMINPUTS 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 AVMINPUTS.

Other Diagnostics and Warnings

    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 avram will try to continue. If you need more than one default extension, consider using the hard coded default extensions of .fun and .avm, or hacking the shell script in which the avram command line appears.

    application-name: empty operator
        This message probably means that the virtual code file is corrupt or invalid.

    usage summary
        For any errors in usage not covered by other diagnostics, such as incompatible combinations of options, avram prints a message to standard error giving a brief summary of options, similar to the output from avram --help.

EXAMPLE
It is recommended that the application developer (or the compiler) package virtual machine code applications as shell scripts with the avram 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.

Here is a script that performs a similar operation to the standard Unix cat 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 chmod) and run by any user with the avram executable in his or her path (even if avram had to be installed in a non-standard directory such as ~/bin).
   #!/bin/sh
   #\
   exec avram --default-to-stdin "$0" "$@"
   sKYQNTP\
The idea for this script is blatantly lifted from the wish 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 avram 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.

When avram 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.

FILES

./profile.txt
    This file is written automatically by avram 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.

ENVIRONMENT
An environment variable AVMINPUTS can be made to store a list of directories (using the set or export commands) that avram will search for input files. The directories should be separated by colons, similarly to the PATH environment variable. The search paths in AVMINPUTS apply only to the names of input files given on the command line when avram 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 AVMINPUTS, avram 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 -.EXT has been used, avram will then search for a file with that name combined with the extension .EXT. If -.EXT has not been used or if no matching file is found with it, avram tries the extensions of .avm and .fun in that order, provided the given file name contained no periods. If no match is found for any of those cases, avram proceeds to search the next directory in the list obtained from AVMINPUTS, 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 AVMINPUTS 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 AVMINPUTS 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
 .:/usr/local/lib/avm:/usr/lib/avm:/lib/avm:/opt/avm:/opt/lib/avm
These paths are defined in avram.c and can be changed by recompiling it.

BUGS
There are no known bugs outstanding, except for any that may be inherent in the external library functions. However, avram 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. avram is designed to recover gracefully from memory overflows by always checking for NULL results from malloc() 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 avram 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.

SEE ALSO
cat(1), libexpect(3), wish(1), bash_builtins(1), ulimit(1), strerror(3), stdin(3), stdout(3), stderror(3), info(1), pinfo(1), chmod(1), set(1), export(1), sh(3). The full documentation for avram is maintained as a Texinfo manual. If the info and avram programs are properly installed at your site, the command info avram or pinfo avram should give you access to the complete manual. Debian GNU/Linux users could have a look under /usr/share/doc/*avram* for possible html or postscript documentation and examples.

AUTHOR
Dennis Furey <avram-support@basis.uklinux.net>.