Initial entry

util/int/int.1

@@ -0,0 +1,200 @@
+.\"	Manual page
+.\"
+.\"	$Header$
+.TH INT I
+.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 inform you about 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