.\" Manual page .\" .\" $Id$ .TH INT 1 "$Revision$" .ad .SH NAME int \- Interpreter for EM Machine Language .SH SYNOPSIS \fBint\fP [ intargs ] [ emfile [ emargs ] ] .SH DESCRIPTION This program interprets the EM machine-language, and replaces the pascal written EM interpreter described in [1]. The program interprets load files in \fIe.out\fP format (see [1], sec. 10.3). .LP \fIEmfile\fP is the name of the load file; if no name is specified, the default name \fIe.out\fP is used. The program can handle several word size / pointer size combinations. The combinations presently supported are 2/2, 2/4 and 4/4. .LP \fIEmargs\fP are the arguments for the program being interpreted. If any arguments are given, then \fIemfile\fP must be present. .PP 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. .PP \fIInt\fP preempts the highest two file descriptors available, for diagnostic purposes. Interpreted programs can use the other file descriptors without clash problems. .PP .I "Interpreter parameters" .br \fIInt\fP itself accepts the following options, all given as separate flags: .IP \fB\-d\fP 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. .IP \fB\-h\fP\fIN\fP The maximum size of the heap will be limited to \fIN\fP bytes. This can be used to force a heap overflow trap. .IP \fB\-I\fP\fIN\fP It is possible to tell \fIint\fP 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 \fIN\fP is the trap number, as described in [1], sec. 9. For ignoring more than one trap, several \fB\-I\fP flags are needed. .IP \fB\-m\fP\fIfile\fP The argument \fIfile\fP is the name of a file on which the messages will appear. The default file name is \fIint.mess\fP. .IP \fB\-r\fP\fIN\fP Determines the size of the Function Return Area. Default: 2 \(mu pointer size. .IP \fB\-s\fP\fIN\fP The maximum size of the stack will be limited to \fIN\fP bytes. This can be used to force a stack overflow trap. .IP \fB\-t\fP If given, a file \fIint.tally\fP 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. .IP \fB\-W\fP\fIN\fP This option can be used to disable warnings. The argument \fIN\fP is the number of the warning to be suppressed, as found in the \fIint\fP documentation [3]. For disabling more than one warning, several \fB\-W\fP flags are needed. .PP .I "The Logging Machine" .br 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 \fImake\fP. These assignments can be interspersed with the options for the EM machine. .PP The logging machine has the following internal variables: .IP \fBLOG\fP=\fIN\fP Logging will start when the instruction count has reached \fIN\fP. .IP \fBLOGMASK\fP=\fIstring\fP 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. \fBLOGMASK\fP=\fIm9\fP means: trace all monitor calls. The action classes are described fully in [3]. The default log mask is reasonably suitable. .IP \fBLOGFILE\fP=\fIstring\fP The \fIstring\fP is the name of a file on which all logging information is written. The default file name is \fIint.log\fP. .IP \fBSTOP\fP=\fIN\fP The logging machine stops the EM machine after instruction \fIN\fP. .PP Stack dumps can be made after each instruction; they are controlled by the pair \fBd4\fP in the log mask; gda and heap dumps can only be made after a specific instruction. The following internal variables pertain to memory dumps: .IP \fBGDA\fP=\fIN\fP The contents of the Global Data Area are dumped after instruction \fIN\fP. The extent can be adjusted by setting \fBGMIN\fP=\fINmin\fP (default 0) and \fBGMAX\fP=\fINmax\fP (default HB). .IP \fBHEAP\fP=\fIN\fP The contents of the heap are dumped after instruction \fIN\fP. .IP \fBSTDSIZE\fP=\fIN\fP The stack dump is restricted to the \fIN\fP topmost bytes. .IP \fBRAWSTACK\fP=\fIN\fP Normally the stack dump produced is divided into activation records separated by formatted dumps of the Return Status Blocks. If \fIN\fP is non-zero, this dividing and formatting is suppressed, and the stack is dumped raw. .PP Some combinations of variable settings are generally useful and can be abbreviated: .IP \fBAT\fP=\fIN\fP Is an abbreviation of \fBLOG\fP=\fIN\-1\fP \fBSTOP\fP=\fIN+1\fP. The default log mask applies. .IP \fBL\fP=\fIstring\fP Is an abbreviation of \fBLOG\fP=\fI0\fP \fBLOGMASK\fP=\fIstring\fP. E.g., \fBL\fP=\fIm9\fP will log all monitor calls and \fBL\fP=\fIA\-Z9\fP will log all instructions (give a full trace). .PP When the interpreter forks, the child continues logging on a new file named \fIint.log_1\fP, etc. In principle it reevaluates the interpreter arguments, now looking for \fBLOG_1\fP, \fBLOGMASK_1\fP, etc., but this feature has not been fully implemented. .PP .I "Diagnostics" .br All diagnostics are written to the message file. Diagnostics come in three flavors: .IP \- (messages): These mention NOP instructions, give more information about incoming signals and display the exit status of the program. .IP \- (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 \fIint\fP documentation [3]. .IP \- (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. .PP Further diagnostics are generated (on \fIstderr\fP) if files cannot be opened or found. .SH "SEE ALSO" e.out(5), ack(1), em22(1), em24(1), em44(1). .IP [1] Andrew S. Tanenbaum, Hans van Staveren, Ed G. Keizer and Johan W. Stevenson, \fIDescription of a Machine Architecture for use with Block Structured Languages\fP, Informatica rapport IR-81. .IP [2] Amsterdam Compiler Kit, reference manual and UNIX manual pages. .IP [3] Eddo de Groot, Leo van den Berge, Dick Grune, \fIThe EM Interpreter\fP. .SH "FILES" .ta 20n int.mess contains messages .br int.log contains logging info, if requested .br int.tally contains tally results, if requested .br int.core produced upon fatal error; format provisional .SH "BUGS" The monitor calls .IR mpxcall , .I ptrace and .I profile have not been implemented. .br The maximum number of bytes for rotation is 4. .br The UNIX V7 struct tchars is not emulated under System V. .br The P and N restrictions on operands are not checked. .br The start-up has a quadratic component in the number of procedures in the EM program. .SH "AUTHORS" L.J.A. van den Berge. .br E.J. de Groot. .br D. Grune