INT(1)

NAME
int - Interpreter for EM Machine Language

SYNOPSIS
int [ intargs ] [ emfile [ emargs ] ]

DESCRIPTION
This program interprets the EM machine-language, and replaces the pascal written EM interpreter described in [1]. The program interprets load files in e.out format (see [1], sec. 10.3).

Emfile is the name of the load file; if no name is specified, the default name e.out is used. The program can handle several word size / pointer size combinations. The combinations presently supported are 2/2, 2/4 and 4/4.

Emargs are the arguments for the program being interpreted. If any arguments are given, then emfile must be present.

The interpreter can generate diagnostic messages (warnings) about the interpreted program. Some of these warnings are given very frequently, which may result in a large, non-functional message file. To avoid this behavior, counters keep track of the number of times a given warning occurs in a given file at a given line number. Only when this counter is a power of 4, the warning will actually be given. `Logarithmic warning generation' is established in this way.

Int preempts the highest two file descriptors available, for diagnostic purposes. Interpreted programs can use the other file descriptors without clash problems.

Interpreter parameters
Int itself accepts the following options, all given as separate flags:

-d  The program will not be run; a disassembly listing of the program will be written to standard output file instead. The original names are lost, but the procedure structure is recovered.

-hN The maximum size of the heap will be limited to N bytes. This can be used to force a heap overflow trap.

-IN It is possible to tell int to ignore traps in the range 0-15. If a trap is ignored, every time the trap would have happened a warning is generated instead. The argument N is the trap number, as described in [1], sec. 9. For ignoring more than one trap, several -I flags are needed.

-mfile
    The argument file is the name of a file on which the messages will appear. The default file name is int.mess.

-rN Determines the size of the Function Return Area. Default: 2 × pointer size.

-sN The maximum size of the stack will be limited to N bytes. This can be used to force a stack overflow trap.

-t  If given, a file int.tally will be produced upon program termination. For each source file, it contains a list of line numbers visited, with the number of times the line was visited and the number of EM instructions executed on the line.

-WN This option can be used to disable warnings. The argument N is the number of the warning to be suppressed, as found in the int documentation [3]. For disabling more than one warning, several -W flags are needed.

The Logging Machine
The EM machine is monitored continually by a Logging Machine. This logging machine keeps an instruction count and can produce a trace of the actions of the EM machine, make readable dumps of the stack, heap and global data area, and stop the EM machine after a given instruction number. The actions of the logging machine are controlled by its internal variables, the values of which can be set by assignments on the command line, much like setting macro names in a call of make. These assignments can be interspersed with the options for the EM machine.

The logging machine has the following internal variables:

LOG=N
    Logging will start when the instruction count has reached N.

LOGMASK=string
    The tracing actions are controlled by a log mask; the log mask consists of a list of pairs of action classes and logging levels. E.g. LOGMASK=m9 means: trace all monitor calls. The action classes are described fully in [3]. The default log mask is reasonably suitable.

LOGFILE=string
    The string is the name of a file on which all logging information is written. The default file name is int.log.

STOP=N
    The logging machine stops the EM machine after instruction N.

Stack dumps can be made after each instruction; they are controlled by the pair d4 in the log mask; gda and heap dumps can only be made after a specific instruction. The following internal variables pertain to memory dumps:

GDA=N
    The contents of the Global Data Area are dumped after instruction N. The extent can be adjusted by setting GMIN=Nmin (default 0) and GMAX=Nmax (default HB).

HEAP=N
    The contents of the heap are dumped after instruction N.

STDSIZE=N
    The stack dump is restricted to the N topmost bytes.

RAWSTACK=N
    Normally the stack dump produced is divided into activation records separated by formatted dumps of the Return Status Blocks. If N is non-zero, this dividing and formatting is suppressed, and the stack is dumped raw.

Some combinations of variable settings are generally useful and can be abbreviated:

AT=N
    Is an abbreviation of LOG=N-1 STOP=N+1. The default log mask applies.

L=string
    Is an abbreviation of LOG=0 LOGMASK=string. E.g., L=m9 will log all monitor calls and L=A-Z9 will log all instructions (give a full trace).

When the interpreter forks, the child continues logging on a new file named int.log_1, etc. In principle it reevaluates the interpreter arguments, now looking for LOG_1, LOGMASK_1, etc., but this feature has not been fully implemented.

Diagnostics
All diagnostics are written to the message file. Diagnostics come in three flavors:

-   (messages): These mention NOP instructions, give more information about incoming signals and display the exit status of the program.

-   (warnings): These are generated as a result of the checking. In most cases the diagnostic is self-explanatory. A complete description of the warnings can be found in the int documentation [3].

-   (fatal errors): This diagnostic is the result of an irrecoverable error, generally before the program has started: incorrect call of the interpreter, cannot access file, incorrect format of load file. A few follow during interpretation: out of memory, uncaught traps, floating point operation on a version without floating point; execution stops immediately after the diagnostic is generated.

Further diagnostics are generated (on stderr) if files cannot be opened or found.

SEE ALSO
e.out(5), ack(1), em22(1), em24(1), em44(1).

[1] Andrew S. Tanenbaum, Hans van Staveren, Ed G. Keizer and Johan W. Stevenson, Description of a Machine Architecture for use with Block Structured Languages, Informatica rapport IR-81.

[2] Amsterdam Compiler Kit, reference manual and UNIX manual pages.

[3] Eddo de Groot, Leo van den Berge, Dick Grune, The EM Interpreter.

FILES
int.mess    contains messages
int.log    contains logging info, if requested
int.tally    contains tally results, if requested
int.core    produced upon fatal error; format provisional

BUGS
The monitor calls mpxcall, ptrace and profile have not been implemented.
The maximum number of bytes for rotation is 4.
The UNIX V7 struct tchars is not emulated under System V.
The P and N restrictions on operands are not checked.
The start-up has a quadratic component in the number of procedures in the EM program.

AUTHORS
L.J.A. van den Berge.
E.J. de Groot.
D. Grune