Pārlūkot izejas kodu

Initial revision

sater 40 gadi atpakaļ
vecāks
revīzija
d608d58ad1
17 mainītis faili ar 2418 papildinājumiem un 0 dzēšanām
  1. 35 0
      man/Makefile
  2. 45 0
      man/a.out.5
  3. 134 0
      man/arch.1
  4. 51 0
      man/arch.5
  5. 86 0
      man/em.1
  6. 31 0
      man/em_cg.6
  7. 39 0
      man/em_decode.6
  8. 50 0
      man/eminform.1
  9. 97 0
      man/libmon.7
  10. 298 0
      man/libpc.7
  11. 63 0
      man/macro.v7
  12. 758 0
      man/pc_prlib.7
  13. 332 0
      man/uni_ass.6
  14. 259 0
      util/ack/ack.1.X
  15. 67 0
      util/ass/em_ass.6
  16. 39 0
      util/misc/em_decode.6
  17. 34 0
      util/opt/em_opt.6

+ 35 - 0
man/Makefile

@@ -0,0 +1,35 @@
+all:
+	-tbl macro.v7 ack.1 | nroff >ack.opr
+	-nroff macro.v7 arch.1 >arch.1.opr
+	-nroff macro.v7 arch.5 >arch.5.opr
+	-nroff macro.v7 libmon.7 > libmon.opr
+	-nroff macro.v7 libpc.7 > libpc.opr
+	-nroff macro.v7 em_ass.6 > em_ass.opr
+	-nroff macro.v7 em_decode.6 > em_decode.opr
+	-nroff macro.v7 em_opt.6 > em_opt.opr
+	-nroff macro.v7 em_pem.6 > em_pem.opr
+	-nroff macro.v7 pc_prlib.7 > pc_prlib.opr
+	-nroff macro.v7 uni_ass.6 >uni_ass.opr
+
+install:
+	-tbl ack.1 >/usr/man/man1/ack.1
+	-cp arch.1 /usr/man/man1/arch.1
+	-cp arch.5 /usr/man/man5/arch.5
+	-cp libmon.7 /usr/man/man7/em_libmon.7
+	-cp libpc.7 /usr/man/man7/em_libpc.7
+	-cp em_ass.6 /usr/man/man6/em_ass.6
+	-cp em_decode.6 /usr/man/man6/em_decode.6
+	-cp em_opt.6 /usr/man/man6/em_opt.6
+	-cp em_pem.6 /usr/man/man6/em_pem.6
+	-cp pc_prlib.7 /usr/man/man7/em_pc_prlib.7
+	-cp uni_ass.6 /usr/man/man6/uni_ass.6
+
+opr:
+	make pr | opr
+
+pr:
+	@make all >make.pr.out 2>&1 &
+	@cat *.opr
+
+clean:
+	-rm -f *.opr

+ 45 - 0
man/a.out.5

@@ -0,0 +1,45 @@
+.TH A.OUT 5
+.SH NAME
+a.out \- universal assembler load format
+.SH DESCRIPTION
+The load files produced by the universal assemblers look very
+much alike.
+These load files consist of sequences of variable length
+records, each describing a part of the initialized memory.
+Bss type memory is left uninitialized by the universal assembler
+and has to be initialized at run-time.
+The EM header em_head will perform this task on most systems.
+Each record consists of a \fIcount\fP, an \fIaddress\fP and
+\fIcount\fP bytes.
+The first byte should be placed at \fIaddress\fP, the second at
+\fIaddress+1\fP, etc.
+
+.nf
+struct loadf {
+        unsigned short  l_addr[2] ;     /* address */
+        short           l_cnt ;         /* count */
+        unsigned char   data[] ;        /* data */
+} ;
+.fi
+
+This representation is machine dependent in two ways.
+First, the byte order in the first three fields is the byte order
+of the machine the universal assembler is running.
+Second, the format of the address differs from machine to machine.
+.br
+For example, for the Intel 8086 the first entry contains a
+16-bit offset and the second entry a segment number.
+The segment number has to be multiplied by 16 and added to
+the addres to obtain the address of the first byte to be
+initialized.
+.br
+The PDP 11 version stores the address in l_addr[0] and the type
+of the initialized memory in l_addr[1].
+Types 1 and 3 are absolute, 4 is text, 5 is data and 6 BSS.
+.br
+For all other currently available machines the
+array of shorts is 'replaced' by a long.
+This long contains the 32-bit address.
+.SH "SEE ALSO"
+uni_ass(VI)
+.SH BUGS

+ 134 - 0
man/arch.1

@@ -0,0 +1,134 @@
+.TH ARCH 1
+.SH NAME
+arch \- archive and library maintainer
+.SH SYNOPSIS
+.B arch
+key [ posname ] afile name ...
+.SH DESCRIPTION
+.I Arch
+maintains groups of files
+combined into a single archive file.
+Its main use
+is to create and update library files as used by a linker.
+It can be used, though, for any similar purpose.
+The Amsterdam compiler kit provides its own archiver with a
+fixed, machine-independent format, much like the UNIX-V7
+archive format.
+EM programs using libraries assume archives in EM format.
+.PP
+.I Key
+is one character from the set
+.B drqtpmx,
+optionally concatenated with
+one or more of
+.B vuaibcl.
+.I Afile
+is the archive file.
+The
+.I names
+are constituent files in the archive file.
+The meanings of the
+.I key
+characters are:
+.TP
+.B d
+Delete the named files from the archive file.
+.TP
+.B r
+Replace the named files in the archive file.
+If the optional character
+.B u
+is used with
+.B r,
+then only those files with
+modified dates later than
+the archive files are replaced.
+If an optional positioning character from the set
+.B abi
+is used, then the
+.I posname
+argument must be present
+and specifies that new files are to be placed
+after
+.RB ( a )
+or before
+.RB ( b
+or
+.BR i )
+.IR posname .
+Otherwise
+new files are placed at the end.
+.TP
+.B q
+Quickly append the named files to the end of the archive file.
+Optional positioning characters are invalid.
+The command does not check whether the added members
+are already in the archive.
+Useful only to avoid quadratic behavior when creating a large
+archive piece-by-piece.
+.TP
+.B t
+Print a table of contents of the archive file.
+If no names are given, all files in the archive are tabled.
+If names are given, only those files are tabled.
+.TP
+.B p
+Print the named files in the archive.
+.TP
+.B m
+Move the named files to the end of the archive.
+If a positioning character is present,
+then the
+.I posname
+argument must be present and,
+as in
+.B r,
+specifies where the files are to be moved.
+.TP
+.B x
+Extract the named files.
+If no names are given, all files in the archive are
+extracted.
+In neither case does
+.B x
+alter the archive file.
+.TP
+.B v
+Verbose.
+Under the verbose option,
+.I arch
+gives a file-by-file
+description of the making of a
+new archive file from the old archive and the constituent files.
+When used with
+.B t,
+it gives a long listing of all information about the files.
+When used with
+.BR p ,
+it precedes each file with a name.
+.TP
+.B c
+Create.
+Normally
+.I arch
+will create
+.I afile
+when it needs to.
+The create option suppresses the
+normal message that is produced when
+.I afile
+is created.
+.TP
+.B l
+Local.
+Normally
+.I arch
+places its temporary files in the directory /tmp.
+This option causes them to be placed in the local directory.
+.SH FILES
+/tmp/v* temporaries
+.SH "SEE ALSO"
+em_ass(I), arch(V),
+.SH BUGS
+If the same file is mentioned twice in an argument list,
+it may be put in the archive twice.

+ 51 - 0
man/arch.5

@@ -0,0 +1,51 @@
+.TH ARCH 5
+.SH NAME
+arch \- archive (library) file format
+.SH SYNOPSIS
+.B #include "/usr/em/h/arch.h"
+.SH DESCRIPTION
+The archive command
+.I arch
+is used to combine several files into
+one.
+Archives are used mainly as libraries to be searched
+by the EM assembler/linker em_ass(VI) or the universal
+assembler/linker em_unias(VI).
+.PP
+A file produced by
+.I arch
+has a magic number at the start,
+followed by the constituent files, each preceded by a file header.
+The magic number and header layout as described in the
+include file are:
+.RS
+.PP
+.nf
+.ta \w'#define 'u +\w'ARMAG 'u
+.so ../h/arch.h
+.fi
+.RE
+.LP
+The name is a null-terminated string;
+The sizes of the other entries are determined as follows:
+long's are 4 bytes in PDP-11 order, int are 2 bytes, low order
+byte first, char's are 1 byte.
+The date is in the
+form of
+.IR time (2);
+the user ID and group ID are numbers; the mode is a bit pattern
+per
+.IR chmod (2);
+the size is counted in bytes.
+.PP
+Each file begins on a even offset;
+a null byte is inserted between files if necessary.
+Nevertheless the size given reflects the
+actual size of the file exclusive of padding.
+.PP
+Notice there is no provision for empty areas in an archive
+file.
+.SH "SEE ALSO"
+arch(I), em_ass(VI), em_unias(VI)
+.SH BUGS
+Coding user and group IDs as characters is a botch.

+ 86 - 0
man/em.1

@@ -0,0 +1,86 @@
+.TH EM I
+.ad
+.SH NAME
+em \- calling program for em interpreters
+.SH SYNOPSIS
+em [-t] [+fcp] [loadfile [args ... ...] ]
+.SH DESCRIPTION
+The loadfile ("e.out" if not specified) is opened to read the first 8 word header.
+The format of this header is explained in e.out(V).
+One of these 8 words is a flag word
+specifying the interpreter options requested at compile time.
+The usual setting of these options is +t -f -c -p.
+One of these options may be overridden at run time
+by the corresponding flag of em.
+Based on these options the name of the appropriate interpreter
+is constructed.
+.PP
+This interpreter is first searched for in /usr/em/mach/pdp/int, then in the current
+directory.
+.PP
+The flags control the following options that can be turned off
+or on by prepending them with - or + respectively:
+.IP t
+run time tests for undefined variables, array bounds etc...
+This option costs a small amount of memory and some time.
+However, it is very useful for debugging.
+.IP p
+profiling of the entire program. The interpreter maintain tables containing
+an estimate of the number of memory cycles used per source line.
+This option is expensive in time as well as in memory space.
+The result tables made at run time are dumped onto a file named
+em_runinf. This file is converted to human readable format
+by the program eminform(I) which writes the profiling information
+on a file called em_profile.
+.IP f
+maintain a bit map of all source lines that have been executed.
+This map is written also onto the file em_runinf and can be interpreted by eminform(I) which writes in this case the file em_flow.
+This option is almost free in time and space.
+.IP c
+count line usage in tables that
+contains for every source line the number of times it
+was entered.
+These tables are also written onto em_runinf.
+Eminform(I) can be used to convert this information into the
+file em_count.
+Cheap in time, expensive in memory space.
+.PP
+These flags
+give rise to 5 different interpreters which are in the
+directory /usr/em/mach/pdp/int
+.PP
+If the interpreter exits with a non-zero exit status, then the line numbers
+of the 64 last executed source lines are dumped on the file
+em_runinf
+in the current directory. Eminform(I) writes this information
+on the human readable file em_last.
+.SH "FILES"
+.IP /usr/em/mach/pdp/int/em_???? 35
+interpreters proper
+.PD 0
+.IP /usr/em/lib/pdp_int/em_????
+source of interpreter
+.IP /usr/em/mach/pdp/int/?+
+positive option switch
+.IP /usr/em/mach/pdp/int/?-
+negative option switch
+.IP em_runinf
+memory dump containing runtime information
+.IP em_profile
+profile data
+.IP em_count
+source line count data
+.IP em_flow
+source line flow data
+.IP em_last
+last lines executed
+.PD
+.SH "SEE ALSO"
+eminform(I), ack(I), int(I)
+.SH BUGS
+Most error messages are self explanatory.
+The interpreter stops in case of lack of space with an error
+message SEGVIO stack overflow.
+If runtime flags are turned on it is advisable to try again
+with the default options.
+Bugs should be reported to Evert Wattel.

+ 31 - 0
man/em_cg.6

@@ -0,0 +1,31 @@
+.TH EM_CG VI
+.ad
+.SH NAME
+em_cg \- EM to assembly code translator
+.SH SYNOPSIS
+/usr/em/lib/mach_cg [-d] [-p\fIn\fP] [-w\fIn\fP] [ infile [ outfile ] ]
+.SH DESCRIPTION
+Em_cg reads a compact EM-program, argument or standard input,
+and produces an assembly program on argument or standard output
+for the machine that is in its name.
+Flags recognized are:
+.IP -d
+Run in debugging mode,
+only possible when the translator is compiled in the right way.
+.IP -p\fIn\fP
+Set the ply to \fIn\fP, default 1.
+The ply is the maximum lookahead depth the code generator may take.
+Effects of this flag are machine dependent.
+.IP -w\fIn\fP
+Set the weight percentage for size to \fIn\fP %, default is 50.
+This sets the size/time tradeoff in the codegenerator.
+Effects are again machine dependent.
+.SH "SEE ALSO"
+ack(I)
+.PD 0
+.IP [1]
+A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan
+Stevenson "Description of a machine architecture for use with
+block structured languages" Informatica report IR-81.
+.SH AUTHOR
+Hans van Staveren, Vrije Universiteit

+ 39 - 0
man/em_decode.6

@@ -0,0 +1,39 @@
+.TH EM_DECODE VI
+.ad
+.SH NAME
+em_decode,em_encode \- compact to readable EM and v.v.
+.SH SYNOPSIS
+/usr/em/lib/em_decode [ inputfile [ outputfile ] ]
+.br
+/usr/em/lib/em_encode [ inputfile [ outputfile ] ]
+.SH DESCRIPTION
+Most programs involved with the EM project only produce and accept
+EM programs in compact form.
+These files are only machine readable.
+A description of this compact form can be found in [1].
+To inspect the code produced by compilers or to patch them for one reason
+or another, you need human readable assembly code.
+Em_decode will do the job for you.
+.PP
+Em_decode accepts the normal compact form in both optimized and
+unoptimized form
+.PP
+Sometimes you have to make some special routines directly
+in EM, for instance the routines implementing the system calls.
+At these times you may use em_encode to produce compact routines
+out of these human readable assembly modules.
+.PP
+The first argument is the input file.
+The second argument is the output file.
+Both programs can act as a filter.
+.SH "SEE ALSO"
+.IP [1]
+A.S.Tanenbaum, Ed Keizer, Hans van Staveren & J.W.Stevenson
+"Description of a machine architecture for use of
+block structured languages" Informatica rapport IR-81.
+.IP [2]
+ack(I)
+.SH DIAGNOSTICS
+Error messages are intended to be self-explanatory.
+.SH AUTHOR
+Johan Stevenson, Vrije Universiteit.

+ 50 - 0
man/eminform.1

@@ -0,0 +1,50 @@
+.tr ~
+.TH EMINFORM I
+.ad
+.SH NAME
+eminform \- converts runtime information of interpreted em to
+human readable form.
+.SH SYNOPSIS
+eminform
+.SH DESCRIPTION
+The EM interpreter, em(I), has several debugging features built in.
+They can be activated by flag options to em(I).
+The EM interpreter collects the information while it runs the program.
+When the program is terminated, the interpreter dumps this information onto
+a file called em_runinf.
+Eminform converts this information in human readable form onto
+a set of files with fixed names, the file em_runinf itself is unlinked.
+.PP
+.in +15
+.ti -13
+~~em_last~~~~A circular buffer is used to keep track of
+the last collection of executed source lines.
+.ti -13
+~~em_flow~~~~A bit map for all source lines tells which lines
+are executed.
+.ti -13
+~~em_count~~~Count the number of times each source line was entered.
+.ti -13
+~~em_profile~Estimate the number of memory cycles
+spent on each source line.
+.in -15
+.LP
+The most common use of eminform is to print the numbers of the last executed
+source lines if an execution error occurred.
+No arguments are needed in this case.
+.LP
+Eminform will create only those files for which there were
+interpreter flags turned on. If no runtime error occurred and
+no flag was turned on the file em_runinf is not created. In
+this case eminform will give the error message "read header
+failed".
+.SH FILES
+em_runinf, em_last, em_flow, em_count, em_profile
+.SH "SEE ALSO"
+ack(I), int(I), em(I).
+.SH BUGS
+If an entire procedure is not touched, the the file name in
+which this procedure occured is unknown.
+If no em_runinf is available the error message is "read header
+failed" and a core dump is created.
+Bugs should be reported to Evert Wattel

+ 97 - 0
man/libmon.7

@@ -0,0 +1,97 @@
+.TH LIBMON VII
+.ad
+.SH NAME
+libmon \- library of system call routines with EM calling sequence
+.SH DESCRIPTION
+The modules in this library contain the UNIX system calls with EM calling sequence.
+This library is written in EM assembly language and can be used
+for interpreted programs, and 'a.out' programs.
+If these routines are used in Pascal programs, then the calling sequence
+requires some attention.
+Some hints may be useful:
+.IP -
+The c-option {$c+} allows you to declare zero-terminated string
+constants in Pascal like "/etc/passwd".
+Moreover, the identifier 'string' is then defined as type identifier for
+a pointer to these zero-terminated strings.
+.IP -
+The d-option {$d+} allows you to use double precision integers (longs).
+The lseek system call, for instance, needs a long argument and returns a long result.
+.IP -
+If the system call requires a pointer as argument use a 'var' parameter.
+For instance declare times as:
+.br
+     procedure times(var t:timesbuf); extern;
+.br
+Note that a 'string' is already a pointer.
+.IP -
+When defining types, use packed records if two bytes must be allocated
+in a single word, as in
+.br
+     device = packed record
+.br
+                minor,major:0..255;
+.br
+              end;
+.IP -
+If a collection of bits is needed, then define an enumerated type and
+a set of this enumerated type. The create mode of a file, for example,
+can be declared as:
+.br
+     modebits = (XHIM,WHIM,RHIM,
+.br
+                 XYOU,WYOU,RYOU,
+.br
+                 XME, WME, RME,
+.br
+                 TEXT,SGID,SUID,... );
+.br
+     creatmode = set of XHIM..SUID;
+.IP -
+There are special system call routines 'uread' and 'uwrite' in libpc(VII),
+because the names 'read' and 'write' are blocked by similar functions in Pascal.
+.PP
+The system call 'signal' exists, but uses 'sigtrp'.
+This EM system call has the
+following calling sequence:
+.br
+     function sigtrp(signo,trapno:integer):integer;
+.br
+The action values of 'signal', odd for 'ignore' and zero
+for 'get back to default',
+may interfere with the EM procedure identification in some
+implementations.
+In most interpreters procedures in EM are numbered consecutively from zero up.
+The first argument of 'sigtrp' is the signal number 'signo' as for 'signal'.
+The second argument is an integer 'trapno', indicating the action to be performed
+when the signal is issued:
+.IP -2 8
+Reset the action for signal 'signo' to the default.
+.IP -3
+Ignore signal 'signo'.
+.IP "0-252"
+Perform an EM instruction TRP with error code 'trapno',
+whenever the signal 'signo' is issued.
+Note that the error codes 0-127 are reserved for EM machine errors
+and language runtime system errors.
+.PP
+The routine 'sigtrp' returns the old 'trapno' or -1 if an erroneous
+signal number is specified.
+Only the signal numbers 1, 2, 3, 13, 14, 15 and 16 may be used as argument
+for 'sigtrp'.
+.SH FILES
+.IP /usr/em/mach/*/lib/tail_mon
+.PD
+.SH "SEE ALSO"
+em(I), ack(I), *(II), libpc(VII)
+.SH DIAGNOSTICS
+All routines put the UNIX error code in the global variable 'errno'.
+Errno is not cleared by successful system calls, so it always gives
+the error of the last failed call.
+One exception: ptrace clears errno when successful.
+.SH AUTHOR
+Ed Keizer, Vrije Universiteit
+.SH BUGS
+There should be additional routines giving a fatal error when they fail.
+It would be pleasant to have routines,
+which print a nice message and stop execution for unexpected errors.

+ 298 - 0
man/libpc.7

@@ -0,0 +1,298 @@
+.TH LIBPC VII
+.ad
+.SH NAME
+libpc \- library of external routines for Pascal programs
+.SH SYNOPSIS
+.ta 11
+const   bufsize = ?;
+.br
+type    br1 =  1..bufsize;
+.br
+        br2 =  0..bufsize;
+.br
+        br3 = -1..bufsize;
+.br
+        ok = -1..0;
+.br
+        buf = packed array[br1] of char;
+.br
+        alfa = packed array[1..8] of char;
+.br
+        string = ^packed array[1..?] of char;
+.br
+        filetype = file of ?;
+.br
+        long = record high,low:integer end;
+
+{all routines must be declared extern}
+
+function        argc:integer;
+.br
+function        argv(i:integer):string;
+.br
+function        environ(i:integer):string;
+.br
+procedure       argshift;
+
+procedure       buff(var f:filetype);
+.br
+procedure       nobuff(var f:filetype);
+.br
+procedure       notext(var f:text);
+.br
+procedure       diag(var f:text);
+.br
+procedure       pcreat(var f:text; s:string);
+.br
+procedure       popen(var f:text; s:string);
+.br
+procedure       pclose(var f:filetype);
+
+procedure       trap(err:integer);
+.br
+procedure       encaps(procedure p; procedure q(n:integer));
+
+function        perrno:integer;
+.br
+function        uread(fd:integer; var b:buf; len:br1):br3;
+.br
+function        uwrite(fd:integer; var b:buf; len:br1):br3;
+
+function        strbuf(var b:buf):string;
+.br
+function        strtobuf(s:string; var b:buf; len:br1):br2;
+.br
+function        strlen(s:string):integer;
+.br
+function        strfetch(s:string; i:integer):char;
+.br
+procedure       strstore(s:string; i:integer; c:char);
+
+function        clock:integer;
+.SH DESCRIPTION
+This library contains some often used external routines for Pascal programs.
+Two versions exist: one for the EM interpreter and another one
+that is used when programs are translated into PDP-11 code.
+The routines can be divided into several categories:
+.PP
+Argument control:
+.RS
+.IP argc 10
+Gives the number of arguments provided when the program is called.
+.PD 0
+.IP argv
+Selects the specified argument from the argument list and returns a
+pointer to it.
+This pointer is nil if the index is out of bounds (<0 or >=argc).
+.IP environ
+Returns a pointer to the i-th environment string (i>=0). Returns nil
+if i is beyond the end of the environment list (UNIX version 7).
+.IP argshift
+Effectively deletes the first argument from the argument list.
+Its function is equivalent to 'shift' in the UNIX shell: argv[2] becomes
+argv[1], argv[3] becomes argv[2], etc.
+It is a useful procedure to skip optional flag arguments.
+Note that the matching of arguments and files
+is done at the time a file is opened by a call to reset or rewrite.
+.PD
+.PP
+.RE
+Additional file handling routines:
+.RS
+.IP buff 10
+Turn on buffering of a file. Not very useful, because all
+files are buffered except standard output to a terminal and diagnostic output.
+Input files are always buffered.
+.PD 0
+.IP nobuff
+Turn off buffering of an output file. It causes the current contents of the
+buffer to be flushed.
+.IP notext
+Only useful for input files.
+End of line characters are not replaced by a space and character codes out of
+the ASCII range (0..127) do not cause an error message.
+.IP diag
+Initialize a file for output on the diagnostic output stream (fd=2).
+Output is not buffered.
+.IP pcreat
+The same as rewrite(f), except that you must provide the filename yourself.
+The name must be zero terminated. Only text files are allowed.
+.IP popen
+The same as reset(f), except that you must provide the filename yourself.
+The name must be zero terminated. Only text files are allowed.
+.IP pclose
+Gives you the opportunity to close files hidden in records or arrays.
+All other files are closed automatically.
+.PD
+.PP
+.RE
+String handling:
+.RS
+.IP strbuf 10
+Type conversion from character array to string.
+It is your own responsibility that the string is zero terminated.
+.PD 0
+.IP strtobuf
+Copy string into buffer until the string terminating zero byte
+is found or until the buffer if full, whatever comes first.
+The zero byte is also copied.
+The number of copied characters, excluding the zero byte, is returned. So if
+the result is equal to the buffer length, then the end of buffer is reached
+before the end of string.
+.IP strlen
+Returns the string length excluding the terminating zero byte.
+.IP strfetch
+Fetches the i-th character from a string.
+There is no check against the string length.
+.IP strstore
+Stores a character in a string. There is no check against
+string length, so this is a dangerous procedure.
+.PD
+.PP
+.RE
+Trap handling:
+.RS
+These routines allow you to handle almost all
+the possible error situations yourself.
+You may define your own trap handler, written in Pascal, instead of the
+default handler that produces an error message and quits.
+You may also generate traps yourself.
+.IP trap 10
+Trap generates the trap passed as argument (0..252).
+The trap numbers 128..252 may be used freely. The others are reserved.
+.PD 0
+.IP encaps
+Encapsulate the execution of 'p' with the trap handler 'q'.
+Encaps replaces the previous trap handler by 'q', calls 'p' and restores
+the previous handler when 'p' returns.
+If, during the execution of 'p', a trap occurs,
+then 'q' is called with the trap number as parameter.
+For the duration of 'q' the previous trap handler is restored, so that
+you may handle only some of the errors in 'q'. All the other errors must
+then be raised again by a call to 'trap'.
+.br
+Encapsulations may be nested: you may encapsulate a procedure while executing
+an encapsulated routine.
+.br
+Jumping out of an encapsulated procedure (non-local goto) is dangerous,
+because the previous trap handler must be restored.
+Therefore, you may only jump out of procedure 'p' from inside 'q' and
+you may only jump out of one level of encapsulation.
+If you want to exit several levels of encapsulation, use traps.
+See pc_emlib(VII) and pc_prlib(VII) for lists of trap numbers
+for EM machine errors and Pascal run time system errors.
+Note that 'p' may not have parameters.
+.PD
+.PP
+.RE
+UNIX system calls:
+.RS
+The routines of this category require global variables or routines
+of the monitor library libmon(VII).
+.IP uread 10
+Equal to the read system call.
+Its normal name is blocked by the standard Pascal routine read.
+.PD 0
+.IP uwrite
+As above but for write(II).
+.IP perrno
+Because external data references are not possible in Pascal,
+this routine returns the global variable errno, indicating the result of
+the last system call.
+.PD
+.PP
+.RE
+Miscellaneous:
+.RS
+.IP clock 10
+Return the number of ticks of user and system time consumed by the program.
+.PD
+.PP
+.RE
+The following program presents an example of how these routines can be used.
+This program is equivalent to the UNIX command cat(I).
+.nf
+     {$c+}
+     program cat(input,inp,output);
+     var inp:text;
+         s:string;
+
+     function argc:integer; extern;
+     function argv(i:integer):string; extern;
+     procedure argshift; extern;
+     function strlen(s:string):integer; extern;
+     function strfetch(s:string; i:integer):char; extern;
+
+     procedure copy(var fi:text);
+     var c:char;
+     begin reset(fi);
+       while not eof(fi) do
+         begin
+           while not eoln(fi) do
+             begin
+               read(fi,c);
+               write(c)
+             end;
+           readln(fi);
+           writeln
+         end
+     end;
+
+     begin  {main}
+       if argc = 1 then
+         copy(input)
+       else
+         repeat
+           s := argv(1);
+           if (strlen(s) = 1) and (strfetch(s,1) = '-')
+             then copy(input)
+             else copy(inp);
+           argshift;
+         until argc <= 1;
+     end.
+.fi
+.PP
+Another example gives some idea of the way to manage trap handling:
+.nf
+
+    program bigreal(output);
+    const EFOVFL=4;
+    var trapped:boolean;
+
+    procedure encaps(procedure p;
+                     procedure q(n:integer)); extern;
+    procedure trap(n:integer); extern;
+
+    procedure traphandler(n:integer);
+    begin if n=EFOVFL then trapped:=true else trap(n) end;
+
+    procedure work;
+    var i,j:real;
+    begin trapped:=false; i:=1;
+      while not trapped do
+        begin j:=i; i:=i*2 end;
+      writeln('bigreal = ',j);
+    end;
+
+    begin
+      encaps(work,traphandler);
+    end.
+.fi
+.SH FILES
+.IP /usr/em/mach/*/lib/tail_pc 20
+.PD
+.SH "SEE ALSO"
+ack(I), pc_pem(VI), pc_prlib(VII), libmon(VII)
+.SH DIAGNOSTICS
+Two routines may cause fatal error messages to be generated.
+These are:
+.IP pcreat 10
+Rewrite error (trap 77) if the file cannot be created.
+.PD 0
+.IP popen
+Reset error (trap 76) if the file cannot be opened for reading
+.PD
+.SH AUTHOR
+Johan Stevenson, Vrije Universiteit.
+.br
+encaps: Ed Keizer, Vrije Universiteit.

+ 63 - 0
man/macro.v7

@@ -0,0 +1,63 @@
+.de TH
+.PD
+.lc
+.nr in 5
+.de hd
+'sp 2
+'tl '\\$1(\\$2)'Amsterdam Compiler Kit'\\$1(\\$2)'
+'sp 2
+\\..
+.wh -6 fo
+.wh 0 hd
+.nr pi 5
+..
+.de fo
+'sp 2
+'tl ''- % -''
+'bp
+..
+.de PD
+.nr pd 0.5v
+.if \\n(.$ .nr pd \\$1
+..
+.de SH
+.nr in 5
+.nr pi 5
+.in \\n(in
+.ti 0
+.sp \\n(pdu
+.ne 2
+.fi
+\s+3\fB\\$1\fP\s0
+.br
+..
+.de LP
+.PP
+..
+.de PP
+.sp \\n(pdu
+.ne 2
+.in \\n(in
+.nr pi 5
+.ns
+..
+.de IP
+.if \\n(.$-1 .nr pi \\$2
+.sp \\n(pdu
+.in \\n(in+\\n(pi
+.ta \\n(in \\n(in+\\n(pi
+.ti 0
+\fB\\$1\fR\c
+.if \w'\fB\\$1\fP'-\\n(pin+1n .br
+..
+.de RS
+.nr in +5
+.in +5
+..
+.de RE
+.in -5
+.nr in -5
+..
+.de RF
+\fI\\$1\fP(\\$2)\\$3
+..

+ 758 - 0
man/pc_prlib.7

@@ -0,0 +1,758 @@
+.TH PC_PRLIB VII
+.ad
+.SH NAME
+pc_prlib \- library of Pascal runtime routines
+.SH SYNOPSIS
+.ta 11
+type    alpha=packed array[1..8] of char;
+.br
+        pstring= ^packed array[] of char;
+
+function        _abi(i:integer):integer;
+.br
+function        _abl(i:long):long;
+.br
+function        _mdi(j,i:integer):integer;
+.br
+function        _mdl(j,i:long):long;
+.br
+function        _abr(r:real):real;
+.br
+function        _sin(r:real):real;
+.br
+function        _cos(r:real):real;
+.br
+function        _atn(r:real):real;
+.br
+function        _exp(r:real):real;
+.br
+function        _log(r:real):real;
+.br
+function        _sqt(r:real):real;
+.br
+function        _rnd(r:real):real;
+
+type    compared=-1..1;
+.br
+        gotoinfo=record
+.br
+            pcoffset:^procedure; { procedure id. without static link }
+.br
+            nlocals: integer;
+.br
+        end;
+
+function        _bcp(sz:integer; s2,s1:pstring):compared;
+.br
+function        _bts(size,high,low:integer; base:^set 0..(8*size-1))
+                        :set of 0..(8*size-1);
+.br
+procedure       _gto(lb:^integer; p:^gotoinfo);
+
+procedure       _new(size:integer; var p:^integer);
+.br
+procedure       _dis(size:integer; var p:^integer);
+.br
+procedure       _sav(var p:^integer);
+.br
+procedure       _rst(var p:^integer);
+
+type    arrdescr=record
+.br
+            lowbnd:  integer;
+.br
+            diffbnds:integer;
+.br
+            elsize:  integer;
+.br
+        end;
+.br
+        arr1=array[] of ?;
+.br
+        arr2=packed array[] of ?;
+
+procedure       _pac(var ad,zd:arrdescr; var zp:arr2; i:integer;
+.br
+                      var ap:arr1);
+.br
+procedure       _unp(var ad,zd:arrdescr; i:integer; var ap:arr1;
+.br
+                      var zp:arr2;);
+.br
+function        _asz(var dp:arrdescr):integer;
+
+procedure       _ass(line:integer; b:boolean);
+.br
+procedure       procentry(var name:alpha);
+.br
+procedure       procexit(var name:alpha);
+
+const   lowbyte=[0..7];
+.br
+        MAGIC  =[1,3,5,7];
+.br
+        WINDOW =[11];
+.br
+        ELNBIT =[12];
+.br
+        EOFBIT =[13];
+.br
+        TXTBIT =[14];
+.br
+        WRBIT  =[15];
+.br
+type    file=record
+.br
+            ptr:     ^char;
+.br
+            flags:   set of [0..15];
+.br
+            fname:   string;
+.br
+            ufd:     0..15;
+.br
+            size:    integer;
+.br
+            count:   0..buflen;
+.br
+            buflen:  max(512,size) div size * size;
+.br
+            bufadr:  packed array[1..max(512,size)]
+.br
+                             of char;
+.br
+        end;
+.br
+        filep=^file;
+.br
+const   NFILES=15;
+.br
+        _extfl:^array[] of filep;
+
+procedure       _ini(var args:integer; var hb:integer;
+                            var p:array[] of filep; var mainlb:integer);
+.br
+procedure       _hlt(status:0..255);
+
+procedure       _opn(size:integer; f:filep);
+.br
+procedure       _cre(size:integer; f:filep);
+.br
+procedure       _cls(f:filep);
+
+procedure       _get(f:filep);
+.br
+procedure       _put(f:filep);
+.br
+function        _wdw(f:filep):^char;
+.br
+function        _efl(f:filep):boolean;
+
+function        _eln(f:filep):boolean;
+.br
+function        _rdc(f:filep):char;
+.br
+function        _rdi(f:filep):integer;
+.br
+function        _rdl(f:filep):long;
+.br
+function        _rdr(f:filep):real;
+.br
+procedure       _rln(f:filep);
+.br
+procedure       _wrc(c:char; f:filep);
+.br
+procedure       _wsc(w:integer; c:char; f:filep);
+.br
+procedure       _wri(i:integer; f:filep);
+.br
+procedure       _wsi(w:integer; i:integer; f:filep);
+.br
+procedure       _wrl(l:long; f:filep);
+.br
+procedure       _wsl(w:integer; l:long; f:filep);
+.br
+procedure       _wrr(r:real; f:filep);
+.br
+procedure       _wsr(w:integer; r:real; f:filep);
+.br
+procedure       _wrf(ndigit:integer; w:integer; r:real; f:filep);
+.br
+procedure       _wrs(l:integer; s:pstring; f:filep);
+.br
+procedure       _wss(w:integer; l:integer; s:pstring; f:filep);
+.br
+procedure       _wrb(b:boolean; f:filep);
+.br
+procedure       _wsb(w:integer; b:boolean; f:filep);
+.br
+procedure       _wrz(s:string; f:filep);
+.br
+procedure       _wsz(w:integer; s:string; f:filep);
+.br
+procedure       _wln(f:filep);
+.br
+procedure       _pag(f:filep);
+.SH DESCRIPTION
+This library is used by the Pascal to EM compiler and
+contains all the runtime routines for standard Pascal programs.
+Most routines are written in C, a few in EM assembly language.
+These routines can be divided into several categories.
+A description of each category with its routines follows.
+.PP
+Arithmetic routines:
+.RS
+.IP _abi
+Compute the absolute value of an integer.
+.PD 0
+.IP _abl
+Compute the absolute value of a long.
+.IP _mdi
+Perform the Pascal modulo operation on integers.
+.IP _mdl
+Perform the Pascal modulo operation on longs.
+.IP _abr
+Compute the absolute value of a real.
+.IP _sin
+Compute the sine of a real.
+.IP _cos
+Compute the cosine of a real.
+.IP _atn
+Compute the arc tangent of a real.
+.IP _exp
+Compute the e-power of a real.
+.IP _log
+Compute the natural logarithm of a real.
+.IP _sqt
+Compute the square root of a real.
+.IP _rnd
+Return a real that when truncated will
+result in the nearest integer (-3.5->-4).
+.PD
+.PP
+.RE
+Miscellaneous routines:
+.RS
+.IP _bcp
+Compare two strings. Use dictionary ordering with the ASCII
+character set. The EM instruction CMU can not be used, because it needs
+an even number of bytes.
+.PD 0
+.IP _bts
+Include a range of elements from low to high in a set of size bytes
+at address base.(size can be divided by the wordsize)
+.IP _gto
+Execute a non-local goto. Lb points to the
+local base of the target procedure.
+A lb of zero indicates a jump to the program body, the lb of the main
+program is found in _m_lb, which is set by _ini.
+The new EM stack pointer is calculated by adding the number of locals
+to the new local base
+(jumping into statements is not allowed; there are no local generators
+in Pascal!).
+.PD
+.PP
+.RE
+Heap management:
+.RS
+.PP
+There is one way to allocate new heap space (_new), but two different
+incompatible ways to deallocate it.
+.PP
+The most general one is by using dispose (_dis).
+A circular list of free blocks, ordered from low to high addresses, is maintained.
+Merging free blocks is done when a new block enters the free list.
+When a new block is requested (_new), the free list is searched using a
+first fit algorithm.
+Two global variables are needed:
+.IP _highp 10
+Points to the free block with the highest address.
+.PD 0
+.IP _lastp
+Points to the most recently entered free block or to a block
+in the neighborhood of the most recently allocated block.
+.PD
+The free list is empty, when one of these pointers (but then at the same
+time both) is zero.
+.PP
+The second way to deallocate heap space is by using
+mark (_sav) and release (_rst). Mark saves the current value of the
+heap pointer HP in the program variable passed as a parameter.
+By calling release with this old HP value as its argument, the old HP value
+is restored, effectively deallocating all blocks requested between
+the calls to mark and release.
+The heap is used as second stack in this case.
+.PP
+It will be clear that these two ways of deallocating heap space
+can not be used together.
+To be able to maintain the free list, all blocks must be a multiple
+of n bytes long, with a minimum of n bytes,
+where n is the sum of the size of a word and a pointer in the
+EM implementation used.
+.PP
+In summary:
+.IP _new
+Allocate heap space.
+.PD 0
+.IP _dis
+Deallocate heap space.
+.IP _sav
+Save the current value of HP.
+.IP _rst
+Restore an old value of HP.
+.PD
+.PP
+.RE
+Array operations:
+.RS
+.PP
+The only useful form of packing implemented, is packing bytes into words.
+All other forms of packing and unpacking result in a plain copy.
+.IP _pac
+Pack an unpacked array 'a' into a packed array 'z'. 'ap' and 'zp'
+are pointers to 'a' and 'z'. 'ad' and 'zd'
+are pointers to the descriptors of 'a' and 'z'. 'i' is
+the index in 'a' of the first element to be packed.
+Pack until 'z' is full.
+.PD 0
+.IP _unp
+Unpack 'z' into 'a'. 'ap', 'zp', 'ad' and 'zd' are as for _pac. 'i' is
+the index in 'a' where the first element of 'z' is copied into.
+Unpack all elements of 'z'.
+.IP _asz
+Compute array size. Used for copying conformant arrays.
+.PD
+.PP
+.RE
+Debugging facilities:
+.RS
+The compiler allows you to verify assertions.
+It generates a call to the routine _ass to check the assertion at runtime.
+Another feature of the compiler is that it enables you to trace the
+procedure calling sequence. If the correct option is turned on, then
+a call to the procedure 'procentry' is generated at the start of each
+compiled procedure or function. Likewise, the routine 'procexit' is called
+just before a procedure or function exits.
+Default procedure 'procentry' and 'procexit' are available in this library.
+.IP _ass 10
+If 'b' is zero, then change eb[0] to 'line'
+(to give an error message with source line number) and call the error routine.
+.PD 0
+.IP procentry
+Print the name of the called procedure with up to seven argument words
+in decimal on standard output. Output must be declared in the program heading.
+.IP procexit
+Print the name of the procedure that is about to exit.
+Same remarks as for procentry.
+.PD
+.PP
+.RE
+Files:
+.RS
+.PP
+Most of the runtime routines are needed for file handling.
+For each file in your Pascal program a record of type file, as described
+above, is allocated, static if your file is declared in the outermost block,
+dynamic if it is declared in inner blocks.
+The fields in the file record are used for:
+.IP bufadr 10
+IO is buffered except for standard input and output if
+terminals are involved. The size of the buffer is the maximum of 512
+and the file element size.
+.PD 0
+.IP buflen
+The effective buffer length is the maximum number of file elements
+fitting in the buffer, multiplied by the element size.
+.IP size
+The file element size (1 or even).
+.IP flags
+Some flag bits are stored in the high byte and a magic pattern
+in the low byte provides detection of destroyed file
+information.
+.IP ptr
+Points to the file window inside the buffer.
+.IP count
+The number of bytes (the window inclusive) left in the buffer
+to be read or the number of free bytes (the window inclusive) for output files.
+.IP ufd
+The UNIX file descriptor for the file.
+.IP fname
+Points to the name of the file (INPUT for standard input,
+OUTPUT for standard output and LOCAL for local files).
+This field is used for generating error messages.
+.PD
+.PP
+The constants used by the file handling routines are:
+.IP WINDOW 10
+Bit in flags set if the window of an input file is initialized.
+Used to resolve the famous interactive input problem.
+.PD 0
+.IP EOFBIT
+Bit in flags set if end of file seen
+.IP ELNBIT
+Bit in flags set if linefeed seen
+.IP TXTBIT
+Bit in flags set for text files. Process linefeeds.
+.IP WRBIT
+Bit in flags set for output files
+.IP MAGIC
+Pattern for the low byte of flags
+.IP NFILES
+The maximum number of open files in UNIX
+.PD
+.PP
+.RE
+Prelude and postlude:
+.RS
+.PP
+These routines are called once for each Pascal program:
+.IP _ini
+When a file mentioned in the program heading is opened by reset or
+rewrite, its file pointer must be mapped onto one of the program
+arguments.
+The compiler knows how to map and therefore builds a table with
+a pointer to the file structure for each program argument.
+One of the first actions of the Pascal program is to call this procedure
+with this table as an argument.
+The global variable _extfl is used to save the address of this table.
+Another task of _ini is to initialize the standard input and output files.
+For standard output it must decide whether to buffer or not.
+If standard output is a terminal, then buffering is off by setting
+buflen to 1.
+Two other task of _ini are the copying of two pointers from
+the argument list to global memory, mainlb to _m_lb and hb to _hbase.
+The first contains the local base of the program body, the second
+contains the address of the hol containing the global variables
+of the program.
+A last task of _ini is to set the global variables _argc, _argv  and _environ
+from args for
+possible reference later on.
+Args points to the argument count placed on the stack by the EM runtime system,
+see chapter 8 in [1].
+.PD 0
+.IP _hlt
+If the program is about to finish, the buffered files must be flushed.
+That is done by this procedure.
+.PD
+.PP
+.RE
+Opening and closing:
+.RS
+.PP
+Files in Pascal are opened for reading by reset and opened for writing by
+rewrite.
+Files to be rewritten may or may not exist already.
+Files not mentioned in the program heading are considered local files.
+The next steps must be done for reset and rewrite:
+.IP 1.
+If size is zero, then a text file must be opened with elements of
+size 1.
+.PD 0
+.IP 2.
+Find out if this file is mentioned in the program heading
+(scan table pointed to by _extfl).
+If not, then it is a local file and goto 7.
+.IP 3.
+If the file is standard input or output then return.
+.IP 4.
+If there are not enough arguments supplied, generate an error.
+.IP 5.
+If the file was already open, flush the buffer if necessary and close it.
+Note that reset may be used to force the buffer to be flushed.
+This is sometimes helpful against program or system crashes.
+.IP 6.
+If it is a reset, open the file, otherwise create it.
+In both cases goto 9.
+.IP 7.
+If the local file is to be written, then close it if it was open and
+create a new nameless file. First try to create it in /usr/tmp, then in /tmp
+and if both fail then try the current directory.
+See to it that the file is open for both reading and writing.
+.IP 8.
+If the local file is to be read
+and the file is opened already, then
+flush the buffer and seek to the beginning.
+Otherwise open a temporary file as described in 7.
+.IP 9.
+Initialize all the file record fields.
+.PD
+.PP
+The necessary procedures are:
+.IP _opn
+Reset a file
+.PD 0
+.IP _cre
+Rewrite a file
+.IP _cls
+Close a file. Closing of files is done for local files when the procedure
+in which they are declared exits.
+The compiler only closes local files if they are not part of a structured type.
+Files allocated in the heap are not closed when they are deallocated.
+There is an external routine 'pclose' in libP(VII), that may be called
+explicitly to do the closing in these cases.
+Closing may be necessary to flush buffers or to keep the number of
+simultaneously opened files below NFILES.
+Files declared in the outermost block are automatically closed when the
+program terminates.
+.PD
+.PP
+.RE
+General file IO:
+.RS
+.PP
+These routines are provided for general file IO:
+.IP _put
+Append the file element in the window to the file and advance the
+window.
+.IP _get
+Advance the file window so that it points to the next element
+of the file.
+For text files (TXTBIT on) the ELNBIT in flags is set if the new character
+in the window is a line feed (ASCII 10) and the character is then changed
+into a space.
+Otherwise the ELNBIT is cleared.
+.IP _wdw
+Return the current pointer to the file window.
+.IP _eof
+Test if you reached end of file.
+Is always true for output files.
+.PD
+.PP
+.RE
+Textfile routines:
+.RS
+.PP
+The rest of the routines all handle text files.
+.IP _eln
+Return true if the next character on an input file is an end-of-line marker.
+An error occurs if eof(f) is true.
+.PD 0
+.IP _rdc
+Return the character currently in the window and advance the window.
+.IP _rdi
+Build an integer from the next couple of characters on the file,
+starting with the character in the window.
+The integer may be preceded by spaces (and line feeds), tabs and a sign.
+There must be at least one digit.
+The first non-digit signals the end of the integer.
+.IP _rdl
+Like _rdi, but for longs.
+.IP _rdr
+Like _rdi, but for reals. Syntax is as required for Pascal.
+.IP _rln
+Skips the current line and clears the WINDOW flag, so that the
+next routine requiring an initialized window knows that it has to
+fetch the next character first.
+.IP _wrc
+Write a character, not preceeded by spaces.
+.IP _wsc
+Write a character, left padded with spaces up to a field width
+of 'w'.
+.IP _wri
+Write an integer, left padded with spaces up to a field width
+of 6.
+.IP _wsi
+Write an integer, left padded with spaces up to a field width
+of 'w'.
+.IP _wrl
+Write a long, left padded with spaces up to a field width
+of 11.
+.IP _wsl
+Write a long, left padded with spaces up to a field width
+of 'w'.
+.IP _wrr
+Write a real in scientific format,
+left padded with spaces up to a field width of 13.
+.IP _wsr
+Write a real in scientific format,
+left padded with spaces up to a field width of 'w'.
+.IP _wrf
+Write a real in fixed point format, with exactly 'ndigit' digits
+behind the decimal point, the last one rounded; it is left padded up to
+a field width of 'w'.
+.IP _wrs
+Write a string of length 'l', without additional spaces.
+.IP _wss
+Write a string of length 'l', left padded up to a field
+width of 'w'.
+.IP _wrb
+Write a boolean, represented by "true" or "false", left padded
+up to a field width of 5.
+.IP _wsb
+Write a boolean, represented by "true" or "false", left padded
+up to a field width of 'w'.
+.IP _wrz
+Write a C-type string up to the zero-byte.
+.IP _wsz
+Write a C-type string, left padded up to a field width of w.
+.IP _wln
+Write a line feed (ASCII 10).
+.IP _pag
+Write a form feed (ASCII 12).
+.PD
+.PP
+.RE
+All the routines to which calls are generated by the compiler are described above.
+They use the following global defined routines to do some of the work:
+.IP _rf 10
+Check input files for MAGIC and WRBIT.
+Initialize the window if WINDOW is cleared.
+.PD 0
+.IP _wf
+Check output files for MAGIC and WRBIT.
+.IP _incpt
+Advance the file window and read a new buffer if necessary.
+.IP _outcpt
+Write out the current buffer if necessary and advance the window.
+.IP _flush
+Flush the buffer if it is an output file.
+Append an extra line marker if EOLBIT is off.
+.IP _wstrin
+All output routines make up a string in a local buffer.
+They call _wstrin to output this buffer and to do the left padding.
+.IP _skipsp
+Skip spaces (and line feeds) on input files.
+.IP _getsig
+Read '+' or '-' if present.
+.IP _fstdig
+See to it that the next character is a digit. Otherwise error.
+.IP _nxtdig
+Check if the next character is a digit.
+.IP _getint
+Do the work for _rdi.
+.IP _ecvt
+Convert real into string of digits for printout in scientific notation.
+.IP _fcvt
+Convert real into string of digits for fixed point printout
+.IP -fif
+Split real into integer and fraction part
+.IP _fef
+Split real into exponent and fraction part
+.PD
+.PP
+The following global variables are used:
+.IP _lastp 10
+For heap management (see above).
+.PD 0
+.IP _highp
+For heap management (see above).
+.IP _extfl
+Used to save the argument p of _ini for later reference.
+.IP _hbase
+Used to save the argument hb of _ini for later reference.
+.IP _m_lb
+Used to store the local base of the main program.
+.IP _curfil
+Save the current file pointer, so that the
+error message can access the file name.
+.IP "_pargc, _pargv, _penvp"
+Used to access the arguments of the main program.
+.PD
+.SH FILES
+.IP /usr/em/lib/mach/*/lib/tail_pc 20
+The library used by ack[5] to link programs.
+.IP /usr/em/etc/pc_rterrors
+The error messages
+.PD
+.SH "SEE ALSO"
+.IP [1]
+A.S. Tanenbaum, Ed Keizer, Hans van Staveren & J.W. Stevenson
+"Description of a machine architecture for use of
+block structured languages" Informatica rapport IR-81.
+.PD 0
+.IP [2]
+K.Jensen & N.Wirth
+"PASCAL, User Manual and Report" Springer-Verlag.
+.IP [3]
+An improved version of the ISO standard proposal for the language Pascal
+ISO/TC97/SC5-N462, received November 1979.
+.IP [4]
+Ed Keizer, "The Amsterdam Compiler Kit reference manual".
+.br
+(try 'nroff /usr/emi/doc/pcref.doc').
+.IP [5]
+ack(I), pc_pem(VI)
+.PD
+.SH DIAGNOSTICS
+All errors discovered by this runtime system cause an EM TRP instruction
+to be executed. This TRP instruction expects the error number on top
+of the stack. See [1] for a more extensive treatment of the subject.
+.PP
+EM allows the user to specify a trap handling routine, called whenever
+an EM machine trap or a language or user defined trap occurs.
+One of the first actions in _ini is to specify that the routine _fatal,
+available in this library, will handle traps.
+This routine is called with an error code (0..252) as argument.
+The file "/usr/em/etc/pc_rterrors" is opened and searched for a message
+corresponding with this number.
+If the file can not be opened, or if the error number is not recorded
+in the file, then the same trap is generated again, but without
+a user-defined trap handler, so that the low levels generate an
+error message.
+Otherwise the following information is printed
+on file descriptor 2:
+.IP -
+The name of the Pascal program
+.PD 0
+.IP -
+The name of the file pointed to by _curfil, if the error number
+is between 96 and 127 inclusive.
+.IP -
+The error message (or the error number if not found).
+.IP -
+The source line number if not equal to 0.
+.PD
+.PP
+The routine _fatal stops the program as soon as the message is printed.
+.PP
+The following error codes are used by the Pascal runtime system:
+.IP 64
+more args expected
+.PD 0
+.IP 65
+error in exp
+.IP 66
+error in ln
+.IP 67
+error in sqrt
+.IP 68
+assertion failed
+.IP 69
+array bound error in pack
+.IP 70
+array bound error in unpack
+.IP 71
+only positive j in 'i mod j'
+.IP 72
+file not yet open
+.IP 73
+dispose error
+.sp
+.IP 96
+file xxx: not writable
+.IP 97
+file xxx: not readable
+.IP 98
+file xxx: end of file
+.IP 99
+file xxx: truncated
+.IP 100
+file xxx: reset error
+.IP 101
+file xxx: rewrite error
+.IP 102
+file xxx: close error
+.IP 103
+file xxx: read error
+.IP 104
+file xxx: write error
+.IP 105
+file xxx: digit expected
+.IP 106
+file xxx: non-ASCII char read
+.PD
+.PP
+.SH AUTHORS
+Johan Stevenson and Ard Verhoog, Vrije Universiteit.
+.SH BUGS
+Please report bugs to the authors.

+ 332 - 0
man/uni_ass.6

@@ -0,0 +1,332 @@
+.tr ~
+.TH UNI_ASS VI
+.ad
+.SH NAME
+uni_ass \- universal assembler/loader
+.SH SYNOPSIS
+/usr/em/lib/\fImachine\fP_as [options] argument ...
+.SH DESCRIPTION
+The universal assembler is a framework allowing easy
+generation of an assembler for any byte oriented machine.
+The framework includes common pseudo instructions for name
+definition, label usage, storage allocation and initialization
+and expression evaluation.
+The resulting program assembles and links assembly modules.
+Arguments may be flags, assembly language modules or libraries.
+.br
+Flags are:
+.IP -d[\fIn\fP]
+Produce a listing on standard output, the octal number
+\fIn\fP is mainly used for debugging purposes.
+The default is 700. 500 and 600 give slightly different
+listings.
+.IP -s[\fIn\fP]
+Produce a human-readable symbol table on standard output.
+The default for \fIn\fP is 3.
+The value 2 causes a listing of only the symbols internal to
+the modules.
+The value 1 causes a listing of external symbols only.
+.IP -o
+The argument following this flag is taken as the name of the
+resulting load file.
+The default name is \fBa.out\fP.
+.PD
+.PP
+The assemblers assemble
+and link together assembly language modules
+machine
+from files and libraries,
+producing an a.out file.
+.PP
+Two different types of arguments are allowed:
+.IP "1-"
+Assembly language modules
+.PD 0
+.IP "2-"
+UNIX archives, as maintained by arch(I). These archives must
+only contain
+assembly language modules with \fI.define\fP as their first
+statement.
+.PD
+.PP
+Note that it is not possible to do a partial load;
+loading starts from assembly language and produces binary
+machine code. No symbol table and no relocation bits are produced.
+.SH "SEGMENTS and TYPES"
+The statements allocating and initializing space,
+like instructions and
+some pseudo-instruction reserve that space in the current
+segment.
+The currently reigning type of segment is determined by
+one of the pseudo-instructions: \fI.text, .data, .bss\fP and
+\&\fI.org\fP.
+The assembler concatenates all space allocated in each of the
+text, data and bss segments.
+That is: every byte in a text segment is followed by another
+byte in the text segment except the last, of which there is
+only one in each program.
+The org segment differs from the other three in the sense that
+the assembler makes no attempt to concatenate pieces of org
+segments.
+Each \fI.org\fP pseudo-instruction has a parameter telling where it
+should start allocating space.
+In the final stages of the assembly the text, data and bss
+segments are concatenated in that order after the length of
+each segment has been made a multiple of a machine dependent
+constant.
+The first segment (text) starts at location 0.
+.br
+The start address of each segment can be set by the .base
+pseudo-instruction.
+.sp
+The labels defined in a particular segment
+have the type of that
+segment, other types are: \fIundefined\fP and \fIabsolute\fP.
+All variables that do not have a value have the type
+\fIundefined\fP, a good example is an unsatisfied external
+reference.
+Numbers have the type \fIabsolute\fP.
+The type of expressions depends on both the operators and the
+operands used.
+Generally, but not always, the following rule holds: whenever
+one of the operands is absolute and the resulting type is that
+of the other operand.
+Not every operation is allowed on every combination of types,
+for example: it is not allowed to add two \fItext\fP values.
+.SH SYNTAX
+.IP letters
+Both upper and lower case may be used and are seen as
+different.
+The underscore '_' is considered to be a letter.
+.IP identifiers
+Identifiers are a sequence of letters and digits, starting with
+a letter or a period '.'.
+Only the first eight characters are remembered by the
+assemblers, identifiers with the same first eight characters
+are considered to be identical.
+Identifiers can, only once, receive a value through assignment or a
+label definition.
+.IP "local labels"
+Local labels consist of a single digit.
+They can only be defined in the label part of a statement and
+used anywhere an identifier is allowed.
+They can be redefined at will.
+Two forms of use exist: \fIf\fPorward and \fIb\fPackward
+references.
+The first consists of the digit followed by an \fIf\fP
+and refers to the first definition of that label following the
+reference.
+The second consists of the digit followed by an \fIb\fP
+and refers to the last definition of the label before the
+reference.
+.IP strings
+Strings are enclosed in single "'" or double """ quotes.
+The use of \eddd where ddd is an octal number and \en, \er,
+\et, \eb and \ef is allowed and has the same meaning as in the
+C language.
+.IP numbers
+Numbers are a sequence of letters and digits, starting with a
+digit.
+No difference is made between small and capital letters.
+.br
+The base of the number is determined in the following way:
+.nf
+if the number ends with an 'h' it is hexadecimal else
+    if the number starts with '0x' it is hexadecimal else
+        if the number starts with '0' it is octal else
+            it's decimal.
+.fi
+Note that the number '0x10h' is an illegal hexadecimal number,
+because 'x' is an illegal hexadecimal digit.
+The number should be written as '0x10' or '10h'.
+The range of numbers depends on the machine.
+A rule of the thumb is that the width of the machine's registers
+the same is as the number of bits allowed in numbers.
+.IP expressions
+The following operators are recognized:
+.nf
+.sp 1
+  op    type       action
+
+   |    binary    bitwise or
+   &    binary    bitwise and
+   ^    binary    bitwise exclusive or
+   +    binary    two's complement addition
+   +    unary     no effect
+   -    binary    two's complement subtraction
+   -    unary     two's complement negation
+   *    binary    two's complement multiplication
+   /    binary    two's complement division
+   %    binary    two's complement remainder
+.tr ~~
+   ~    unary     one's complement negation
+.tr ~
+.sp 1
+.fi
+The operator precedence is the same as in C.
+.br
+The operands allowed are: identifiers, numbers and expressions.
+The evaluation order can be changed using the brackets '[' and
+\&']'.
+.sp
+.IP comment
+The character '!' denotes the start of comment, every character
+up to the next newline is skipped.
+Exclamation marks in strings are not recognized as the start of
+comment.
+.IP statements
+Statements are separated by newlines and ';' and can be
+preceded by label definitions.
+Label definitions have the form "\fIidentifier\fP~:" or
+"\fIdigit\fP~:".
+Statements can be: empty, an assignment, an instruction or a
+pseudo-instruction.
+.IP assignment
+An assignment has the form:
+.br
+        \fIidentifier\fP = \fIexpression\fP
+.br
+The identifier receives the value and type of the expression.
+.IP instruction
+The syntax of an instruction depends on the type of the target
+machine.
+An example of a assembly file is presented at
+the end of the document.
+.IP pseudo-instruction
+.de Pu
+.sp 1
+.ti +5
+\&\\$1
+.sp 1
+..
+.Pu ".extern \fIidentifier [, identifier]*\fP"
+The identifiers mentioned in the list are exported and can be
+used in other modules.
+.Pu ".define \fIidentifier [, identifier]*\fP"
+Used for modules that are to be part of a libary.
+The .define pseudo's should be the first in such modules.
+When scanning a module in a library the univeral assembler
+checks whether any of its unsatified external references is
+mentioned in a .define list. If so, it includes that module in
+the program.
+The identifiers mentioned in the list are exported and can be
+used in other modules.
+.Pu ".byte \fIexpression [, expression]*\fP"
+Initialize a sequence of bytes.
+This is not followed by automatic alignment.
+.Pu ".short \fIexpression [, expression]*\fP"
+Initialize a sequence of shorts (2-byte values).
+This is not followed by automatic alignment.
+.Pu ".long \fIexpression [, expression]*\fP"
+Initialize a sequence of longs (4-byte values).
+This is not followed by automatic alignment.
+.Pu ".word \fIexpression [, expression]*\fP"
+Initialize a sequence of words. The number of bytes occupied by
+a word depends on the target machine.
+This is not followed by automatic alignment.
+.Pu ".ascii \fIstring\fP"
+Initialize a sequence of bytes with the value of the bytes in
+the string.
+This is not followed by automatic alignment.
+.Pu ".asciz \fIstring\fP"
+Initialize a sequence of bytes with the value of the bytes in
+the string and terminate this with an extra zero byte.
+This is not followed by automatic alignment.
+.Pu ".align [\fIexpression\fP]"
+Adjust the current position to a multiple of the value of the
+expression.
+The default is the word-size of the target machine.
+.Pu ".space \fIexpression\fP"
+Allocate the indicated amount of bytes.
+The expression must be absolute.
+.Pu ".org \fIexpression\fP"
+Start an org segment with the location counter at the indicated
+value.
+The value of the expression must be absolute.
+.Pu ".text"
+.Pu ".data"
+.Pu ".bss"
+Start an segment of the indicated type.
+.Pu ".base \fIexpresssion\fP"
+Set the starting address of the current segment to the value of
+the expression.
+The expression must be absolute.
+.Pu ".errnz \fIexpression\fP"
+Stop with a fatal error message when the value of the
+expression is non-zero.
+.SH "SEE ALSO"
+ack(I), arch(I), a.out(V)
+.SH "EXAMPLE"
+An example of INtel 8086 assembly code.
+.sp 2
+.nf
+.ta 8 16 32 40 48 56 64
+	.define begbss
+	.define hol0,.diverr,.reghp
+	.define EIDIVZ
+
+	EIDIVZ          = 6
+
+	base            = 0x01C0
+	topmem          = 0xFFF0
+
+		.org    topmem-16
+	.extern __n_line
+	maxmem:
+	__n_line:
+		.space  16
+		.errnz  __n_line-0xFFE0
+
+		.base   base
+
+		.text
+		cld
+		xor     ax,ax
+		mov     (2),cs
+		mov     (0),.diverr
+		mov     sp,maxmem
+		mov     di,begbss
+		mov     cx,[[endbss-begbss]/2]&0x7FFF
+		! xor     ax,ax ! ax still is 0
+		rep stos
+		mov     ax,1
+		push    ax
+		call    _start
+	3:
+		jmp	3b
+	.diverr:
+		push    ax
+		mov     ax,EIDIVZ
+		call    .error
+		pop     ax
+		iret
+		cmp	0,4(bx)(di)	! just to show this addr. mode
+
+		.data
+	begdata:
+	hol0:
+		.word   0,0
+		.word   0,0
+		.word   3f
+	.reghp:
+		.word   endbss
+	3:
+		.asciz "PROGRAM"
+	.sp 3
+.fi
+.SH DIAGNOSTICS
+Various diagnostics may be produced.
+The most likely errors, however, are unresolved references,
+probably caused by the omission of a library argument.
+.SH BUGS
+The resulting a.out file contains no information about the size
+and starting address of the segments.
+.br
+The resulting a.out file does not contain a symbol table.
+.br
+The alignment might give rise to internal assertion errors when
+the alignment requestes is larger than the machine dependent
+segment alignment.
+.br
+Identifiers declared as externals cannot be used as locals in
+any following module.

+ 259 - 0
util/ack/ack.1.X

@@ -0,0 +1,259 @@
+.TH ACK I
+.ad
+.SH NAME
+ack \- Amsterdam Compiler Kit
+.SH SYNOPSIS
+\fBack\fP arguments
+.br
+\fBacc\fP arguments
+.br
+\fBapc\fP arguments
+.br
+\fImachine\fP arguments
+.SH DESCRIPTION
+This program transforms sources in several
+languages to load files for a variety of machines,
+internally using several phases.
+The transformation can be stopped at any phase.
+Combining sources from several languages is allowed.
+The run-time system of the first language mentioned,
+either in the program call name or in the arguments,
+is automatically included.
+The libraries of all other languages mentioned,
+containing most of the run-time systems,
+are also automatically included.
+Two types of load files can be distinguished,
+\fIa.out\fP files containing machine code and \fIe.out\fP
+files containing virtual EM machine code.
+The last type is designed for interpretation.
+Compilation time for interpretation is fast and gives many
+runtime checks,
+but execution is about seven times slower.
+Which combinations of languages and machines are allowed varies
+in time and depends on the installation.
+.PP
+The actions of \fIack\fP are to repeatedly transform files with a
+particular suffix into files with another suffix,
+finally combining the results into a load file.
+.PP
+\fIAck\fP recognizes the following suffixes:
+.IP .p
+Pascal program.
+.IP .c
+C module.
+.IP .e
+EM assembly module in human readable form.
+.IP .k
+Compact EM assembly code.
+.IP .m
+Optimized compact EM assembly code.
+.IP .s
+Machine assembly language code.
+.IP .o
+Object file.
+.PP
+\fIAck\fP accepts the following flags:
+.IP \-m\fImachine\fP
+This flag tells \fIack\fP to generate a load file for \fImachine\fP.
+\fIMachine\fP can also be used as the program call
+name, instead of \fIack\fP.
+e.g. \fIack \-m8086 file.p\fP is equivalent to \fI8086
+file.p\fP.
+.IP \-o
+The the next argument as the name of the resulting load file,
+instead of the default \fIa.out\fP or \fIe.out\fP.
+.IP \-O
+Use the EM peephole optimizer,
+this flag is superfluous when an machine code is generated.
+.IP \-LIB
+This flag tells the peephole optimizer
+.RF em_opt VI
+to add information about the visibility of the names used
+to each output module.
+This is needed by most
+assembler/linkers when these modules are to be inserted
+in libraries.
+.IP \-l\fIname\fP
+Tells \fIack\fP to insert a library module at this point.
+For example: the library \fImon\fP contains the
+routines for systems calls needed by both C and Pascal.
+.IP \-r.\fIsuffix\fP
+Most frontends and backends use one or
+more run-time libraries.
+These flags tell \fIack\fP to include the libraries needed when
+a file with \fIsuffix\fP would be included in the arguments.
+.IP \-L
+Disable the generation of code by the front ends to
+record line number and source file name at run-time.
+.IP \-p
+This flag tells both the Pascal and C front ends to include
+code enabling the user to do some monitoring/debugging.
+Each time a routine is entered the routine \fBprocentry\fP
+is called and just before each return \fBprocexit\fP is called.
+These routines are supplied with one parameter, a pointer
+to a string containing the name of the routine.
+.IP \-w
+Suppress all warning messages.
+.IP \-v
+Verbose.
+Print information while juggling with files.
+.IP \-g
+Try to run the resulting load file.
+No arguments can be passed this way,
+so it is only useful in simple cases.
+.IP \-I\fIdir\fP
+\&\`#include\' files whose names do not begin with \`/\' are
+always sought first in the directory of the \fIfile\fP argument,
+then in the directories named in \fB\-I\fP options,
+then in directories on a standard list.
+.IP \-D\fIname=def\fP
+.IP \-D\fIname\fP
+Define the \fIname\fP to the preprocessor,
+as if by \`#define\'.
+If no definition is given the \fIname\fP is defined as 1.
+.IP \-U\fIname\fP
+Remove any initial definition of \fIname\fP, before
+preprocessing.
+.IP \-c\fI.suffix\fP
+.IP \-c
+\fIAck\fP tries to transform each source into a file with the \fIsuffix\fP.
+When no \fIsuffix\fP is specified \fIack\fP stops just
+before the phase where it combines all arguments into a load file,
+thereby transforming the sources into \fI.k\fP, \fI.s\fP,
+\&\fI.o\fP or \fI.m\fP files.
+One extra \fIsuffix\fP is recognized here, \fI.i\fP,
+this tells \fIack\fP to only preprocess all human readable sources,
+producing files with \fIsuffix\fP \fI.i\fP.
+Note: \fIack\fP refuses to overwrite argument \fI.e\fP files.
+.IP \-t
+Preserve all intermediate files.
+.IP \-k
+Do not stop when an error occurs, but try to transform all
+other arguments as far as possible.
+.IP \-R\fIprogram=xxx\fP
+Replace the \fIprogram\fP by the pathname \fIxxx\fP.
+The program names referred to later in this manual are allowed here.
+.IP \-R\fIprogram\-xxx\fP
+The flag argument \fI\-xxx\fP is given to \fIprogram\fP.
+.IP \-E
+Produce a complete listing of each Pascal source program.
+Normally for each error, one message,
+including the source line number, is given.
+.IP \-e
+List only the erroneous lines of each Pascal source program.
+.IP \-{xxx}
+The string starting after \`{\' and terminated by a \`}\' is passed
+as an option string to the Pascal compiler and supersedes corresponding
+options given in the source file.
+See the ACK reference manual [4] for a list of options.
+.IP "\-+xxx, \-\-xxx"
+When you want to interpret your program, you may select some
+options during interpretation, like test, profile, flow, extra and count.
+A short description of these flags follows:
+.RS
+.IP "  t(est)" 12
+test for undefined, overflow, array bound etc.
+.IP "  f(low)"
+keep track of executed source lines.
+.IP "  c(ount)"
+count the number of times a source line is executed.
+.IP "  p(rofile)"
+count the memory cycles executed per source line.
+.RE
+.IP "" 5
+Test is on by default, the others are off. Normally, you give these
+flag options each time you run the interpreter.
+The EM assembler/linker gives you the opportunity to change
+the defaults per program.
+The changed options are recorded in the "e.out" header.
+These flags \-\- and \-+ are passed to the assembler for this purpose.
+So, \-\-t and \-+pfce invert the defaults.
+.IP \-.\fIsuffix\fP
+When linking multiple \fI.o\fP or \fI.m\fP files created by
+separate calls of \fIack\fP together, \fIack\fP cannot deduce
+the run-time system needed,
+unless called as \fIapc\fP or \fIacc\fP.
+This flag serves to tell \fIack\fP which runtime system is
+needed in such a case.
+For example: "ack \-c x.c ; ack \-.c x.o".
+.PP
+All arguments without a suffix or with an unrecognized suffix
+are passed to the loaders, as for flags.
+.SH PREPROCESSOR
+All C source programs are run through the preprocessor
+before they are fed to the compiler proper.
+Other human readable sources (Pascal programs and
+machine assembly) are only preprocessed when they start with a \`#\'.
+.PP
+\fIAck\fP adds a few macro definitions when it calls the
+preprocessor.
+These macro\'s contain the word- and pointer-size and the sizes
+of some basic types used by the Pascal and/or C compiler.
+All sizes are in bytes.
+.PP
+.TS
+tab(:);
+l l l l.
+EM_WSIZE:wordsize:EM_PSIZE:pointer size
+EM_SSIZE:size of shorts (C):EM_LSIZE:size of longs (C+Pascal)
+EM_FSIZE:size of floats (C):EM_DSIZE:size of doubles (C+Pascal)
+.TE
+.PP
+The name of the \fImachine\fP or something like it when
+the machine name is numeric is also defined (as 1).
+.SH PROGRAMS
+\fIAck\fP uses one or more programs in each phase of the
+transformation.
+The table below gives the names \fIack\fP uses for these
+programs.
+Internally \fIack\fP maintains a mapping of these names to pathnames
+for load files.
+The table specifies which type of files are accepted by each
+program as input and the file type produced as output.
+.TS
+tab(:);
+l l l l.
+input:name:output:description
+\&.c:cem:.k:C front end [4,5,6]
+\&.p:pc:.k:Pascal front end [2,3,6]
+\&.e:encode:.k:Compactify EM assembly language [1]
+\&.k:opt:.m:EM peephole optimizer
+\&.k .m:decode:.e:Produce human readable EM assembly
+\&.k .m:emass:e.out:Linker producing EM machine code [1]
+\&.m:be:.s:backend
+\&.s:asld:a.out:Assembler/linker producing machine code
+\&.s:as:.o:Assembler
+\&.o:ld:a.out:Linker producing machine code
+.TE
+.SH "SEE ALSO"
+.PD 0
+em_opt(VI), em_ass(VI), em_cg(VI)
+.IP [1]
+A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan
+Stevenson "Description of a machine architecture for use with
+block structured languages" Informatica report IR-81.
+.IP [2]
+K. Jensen and N. Wirth
+"PASCAL, User manual and report" Springer Verlag.
+.IP [3]
+The ISO Pascal standard proposal ISO/TC97/SC5-N462.
+.IP [4]
+B.W. Kernighan and D.M. Ritchie, \fIThe C Programming
+language\fP, Prentice-Hall, 1978
+.IP [5]
+D.M. Ritchie, \fI C Reference Manual\fP
+.IP [6]
+E.G. Keizer, Amsterdam Compiler Kit, reference manuals and UNIX manual pages.
+.PD
+.SH DIAGNOSTICS
+.PD
+The diagnostics are intended to be self\-explanatory.
+.SH BUGS
+The -g flag is inoperative.
+.br
+Not all warning messages are superseded by \fB\-w\fP.
+.br
+Argument assembly files are not preprocessed when fed into the
+universal assembler.
+.SH AUTHOR
+Ed Keizer, Vrije Universiteit, Amsterdam

+ 67 - 0
util/ass/em_ass.6

@@ -0,0 +1,67 @@
+.TH EM_ASS VI
+.ad
+.SH NAME
+em_ass \- EM assembler/loader
+.SH SYNOPSIS
+/usr/em/lib/em_ass [options] argument ...
+.SH DESCRIPTION
+Em_ass assembles and links EM modules.
+Arguments may be flags, EM modules or libraries.
+Flags recognized are:
+.IP "-ss, -sm, -sl"
+Indicate that your program is small, medium or large.
+Medium is the default.
+.IP -p
+List all procedure names together with base-address (decimal and octal),
+procedure number and module of definition.
+.IP -d
+Used for debugging em_ass itself.
+.PD
+.PP
+em_ass assembles and links together compact EM assembly language modules
+from files and libraries,
+producing an e.out file as described in [1].
+.PP
+Two different types of arguments are allowed:
+.IP "1 -"
+Compact EM assembly language modules (optimized or not), recognized by a
+magic number in the first word.
+.PD 0
+.IP "2 -"
+UNIX archives, as maintained by arch(I). These archives must contain
+EM modules only.
+.PD
+.PP
+EM modules may contain a library message specifying the names
+of procedures and external data defined inside the module.
+These will only be loaded
+if they contain definitions of procedures or data imported by
+previously assembled modules.
+When \fIack\fP(I) is provided with the -LIB flag it tells the
+EM-optimizer \fIem_opt\fP(VI) to insert a library messages
+when optimizing modules.
+The EM-archiver \fIarch\fP(I) can be used to create libraries
+from EM modules.
+.PP
+Note that it is not possible to do a partial load;
+loading starts from compact EM code and produces binary
+EM code. No symbol table and no relocation bits are produced.
+.SH "SEE ALSO"
+ack(I), arch(I)
+.PD 0
+.IP [1]
+A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan
+Stevenson "Description of a machine architecture for use with
+block structured languages" Informatica report IR-81.
+.SH DIAGNOSTICS
+Various diagnostics may be produced. In the case of compiler
+produced code the only messages to expect are "Out of memory"
+or of the
+form: Overflow in XXXX. The latter can usually be cured by giving
+a -sl flag,
+the former means your program is too big, dimishing
+the size of very large procedures can sometimes help.
+The most likely errors, however, are unresolved references,
+probably caused by the omission of a library argument.
+.SH AUTHOR
+Ed Keizer, Vrije Universiteit

+ 39 - 0
util/misc/em_decode.6

@@ -0,0 +1,39 @@
+.TH EM_DECODE VI
+.ad
+.SH NAME
+em_decode,em_encode \- compact to readable EM and v.v.
+.SH SYNOPSIS
+/usr/em/lib/em_decode [ inputfile [ outputfile ] ]
+.br
+/usr/em/lib/em_encode [ inputfile [ outputfile ] ]
+.SH DESCRIPTION
+Most programs involved with the EM project only produce and accept
+EM programs in compact form.
+These files are only machine readable.
+A description of this compact form can be found in [1].
+To inspect the code produced by compilers or to patch them for one reason
+or another, you need human readable assembly code.
+Em_decode will do the job for you.
+.PP
+Em_decode accepts the normal compact form in both optimized and
+unoptimized form
+.PP
+Sometimes you have to make some special routines directly
+in EM, for instance the routines implementing the system calls.
+At these times you may use em_encode to produce compact routines
+out of these human readable assembly modules.
+.PP
+The first argument is the input file.
+The second argument is the output file.
+Both programs can act as a filter.
+.SH "SEE ALSO"
+.IP [1]
+A.S.Tanenbaum, Ed Keizer, Hans van Staveren & J.W.Stevenson
+"Description of a machine architecture for use of
+block structured languages" Informatica rapport IR-81.
+.IP [2]
+ack(I)
+.SH DIAGNOSTICS
+Error messages are intended to be self-explanatory.
+.SH AUTHOR
+Johan Stevenson, Vrije Universiteit.

+ 34 - 0
util/opt/em_opt.6

@@ -0,0 +1,34 @@
+.TH EM_OPT VI
+.ad
+.SH NAME
+em_opt \- EM peephole optimizer
+.SH SYNOPSIS
+/usr/em/lib/em_opt [-Ln] [ argument ]
+.SH DESCRIPTION
+Em_opt reads a compact EM-program, argument or standard input,
+and produces another compact EM program on standard output
+that is functionally equivalent,
+but smaller.
+Some other functions are here that make this program mandatory
+before running a codegenerator,
+it may be left out when interpretation is wanted.
+Flags recognized are:
+.IP -L
+Make a library module.
+This means that the output will start with a message giving
+the names of all exported entities in this module.
+.IP -n
+Do not optimize.
+No peephole optimizations will be performed,
+other functions will be carried out.
+.SH "FILES"
+/usr/tmp/emopt??????, is used when the -L flag is given only.
+.SH "SEE ALSO"
+ack(I)
+.PD 0
+.IP [1]
+A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan
+Stevenson "Description of a machine architecture for use with
+block structured languages" Informatica report IR-81.
+.SH AUTHOR
+Hans van Staveren, Vrije Universiteit