.\" Copyright Warren Toomey
.\"
.\" $Revision: 1.10 $
.\" $Date: 2008/05/15 03:20:52 $
.\"
.Dd December, 2000
.Dt APOUT 1
.Os
.Sh NAME
.Nm apout
.Nd run PDP-11 UNIX a.out binaries
.Sh SYNOPSIS
.Nm apout
.Op Fl inst
.Op Fl trap
.Op Fl jsr
.Op Fl fp
.Ar file
.Op Ar arguments ...
.Sh DESCRIPTION
.Nm apout
runs the
.Ar file
which contains a PDP-11 UNIX a.out binary from one of the following
versions of UNIX: 1st Edition, 2nd Edition, 5th Edition, 6th Edition,
7th Edition, 2.9BSD or 2.11BSD. Any arguments after the named
.Ar file
are passed as arguments to the a.out binary.
.Pp
User-mode PDP-11 instructions are interpreted and executed by
.Nm apout,
and system calls made by the interpreted a.out binary are performed
by making real systems calls to the underlying native operating system.
In this way, the interpreted a.out binary can interact with the real
files and processes on the system.
.Pp
If
.Nm apout
has been compiled with debugging enabled, the following options are available:
.Bl -tag -width trap
.It Fl inst
Output a line for each instruction emulated which gives:
the PC in octal, the instruction in octal, the instruction's name,
r0 to r6 in octal, and the values of the N, Z, V and C flags.
.It Fl trap
Output a line for each system call, which gives the name of the system
call, possibly a list of arguments, and the value returned by the system
call.
.It Fl jsr
Output a line for each
.Ar jsr
or
.Ar rts
giving the value of the new PC. For 2.11BSD overlay binaries, also output
a line describing each overlay change.
.It Fl fp
For many of the emulated floating-point instructions, output a line
describing the operation.
.El
.Pp
If
.Nm apout
was not compiled with debugging enabled, none of these options exist.
Any debugging output is directed to the file
.Ar apout.dbg
in the directory where
.Nm apout
was started. The debugging output is primarily designed to aid the
developers of
.Nm apout,
and so it isn't exhaustive for all instructions, traps or floating-point
operations.
.Sh ENVIRONMENT VARIABLES
.Nm apout
requires one environment variable to be set:
.Ev APOUT_ROOT.
This variable names the `root' of the emulated filesystem.
.Pp
When
.Nm apout
works with filenames, if the filenames are relative, then they
stay relative i.e all files on the system can be named, as long as they are
given relative names. However, if the filenames are absolute, i.e they
start with a slash, then
.Nm apout
prepends the value of the environment variable
.Ev APOUT_ROOT
to the filename. Therefore, if you have the 7th Edition files located in
.Ar /usr/misc/v7root
and you do:
.Bd -literal
    %  setenv APOUT_ROOT /usr/misc/v7root
    %  apout $APOUT_ROOT/bin/sh
    $
.Ed
.Pp
then you will be greeted with the 7th Edition Bourne shell prompt as shown:
you will still be in the directory where you started
.Nm apout,
but if you cd to /, then you will be taken to
.Ar /usr/misc/v7root
.Pp
Note that you must set
.Ev APOUT_ROOT
before you can run 
.Nm apout.
.Pp
There is one other optional environment variable:
.Ev APOUT_UNIX_VERSION.
This is mainly required for UNIX binaries that use the 0407 header,
which was used across several versions of UNIX, each with a different set
of system calls. If APOUT_UNIX_VERSION is set,
.Nm apout
will use the given version when it cannot determine which version of UNIX a
binary belongs to. The available values are "V1", "V2", "V3", "V4", "V5", "V6",
"V7", "2.9BSD" and "2.11BSD".
.Pp
.Sh EMULATED ENVIRONMENT VARIABLES
Initially, PDP-11 binaries run via
.Nm apout
receive the following set of emulated environment variables:
.Bd -literal
    PATH  /bin:/usr/bin:/usr/sbin:/usr/ucb:/usr/games:/usr/local/bin:.
    HOME  /
    TERM  vt100
.Ed
.Pp
Emulated programs can, of course, change this emulated environment;
they can also fork and exec other PDP-11 binaries, which will inherit the
modified emulated environment.
.Sh INTERACTION WITH NATIVE PROGRAMS
Binaries that are interpreted by
.Nm apout
can interact with native programs in several ways: through files in the
filesystem, and through pipes. For example, you can do the following:
.Bd -literal
    %  ls -lR | apout $APOUT_ROOT/bin/wc | lpr
    %  apout $APOUT_ROOT/bin/sort < file | uniq > newfile
.Ed
.Pp
where
.Ar ls,
.Ar lpr
and
.Ar uniq
are native programs.
.Pp
If
.Nm apout
is compiled with the NATIVES preprocessor directive enabled, then native system
binaries can be executed as well as PDP-11 binaries. For example:
.Bd -literal
    % cd $APOUT_ROOT
    % ln -s `which vi` bin/vi       Add vi into the filespace
    % apout bin/sh
    $ ls -l                         Run the PDP-11 ls
      ....
    $ vi kim.c                      Run the native vi
    $ cc -o kim kim.c               Compile with the PDP-11 compiler
.Ed
.Pp
Note that native executable receive the same environment variables inherited
by the
.Nm apout
process, and not the emulated environment that
.Nm apout
passes to emulated executables.
.Sh ERROR MESSAGES
So as to distinguish from error messages generated by the interpreted PDP-11
binaries,
.Nm apout
prepends the word `Apout' to the beginning of its error messages. Below is
the list of error messages that
.Nm apout
can generate:
.Bd -ragged
   Apout - V1 sectosixty too big
   Apout - can't malloc overlay!
   Apout - can't switch to empty overlay %d
   Apout - could not read 1st line of script
   Apout - couldn't load %s
   Apout - open_dir couldn't open %s
   Apout - out of argv space in script
   Apout - pid %d bad FP register used at PC 0%o
   Apout - pid %d bpt instruction at PC 0%o
   Apout - pid %d bus error at PC 0%06o
   Apout - pid %d emt instruction at PC 0%o
   Apout - pid %d halt instruction at PC 0%o
   Apout - pid %d illegal instruction %o at PC 0%o
   Apout - pid %d iot instruction at PC 0%o
   Apout - pid %d mark instruction at PC 0%o
   Apout - pid %d mfpd instruction at PC 0%o
   Apout - pid %d mtpd instruction at PC 0%o
   Apout - pid %d segmentation fault at PC 0%06o
   Apout - pid %d trap instruction at PC 0%o
   Apout - pid %d unimplemented instruction at PC 0%o
   Apout - pid %d unknown KE11 register 0%o
   Apout - pid %d waiti instruction at PC 0%o
   Apout - the %s syscall is not yet implemented
   Apout - the 2.11BSD %s syscall is not yet implemented
   Apout - unknown a.out format 0%o
   Apout - unknown magic in header: 0x%x
   Apout - unknown syscall %d at PC 0%o
   Apout cannot set the environment for the a.out %s
   Apout not compiled to support 1st Edition binaries
   Apout not compiled to support 2nd Edition binaries
   Apout not compiled to support 2.11BSD binaries
.Ed
.Sh CAVEATS
As far as is known, the emulation of user-mode integer instructions is correct.
The emulation of floating-point instructions is seriously deficient:
only 32-bit floats are emulated: the extra 32-bits of precision in PDP-11
doubles goes unused. None of the FP errors are emulated.
.Pp
The emulation of each of the emulated UNIX environments is mostly,
but not fully, complete. Any UNIX system call environment is very
sophisticated, and
.Ar apout
must translate from the emulated UNIX environment to the native one, and
back. For an authorative description of what is missing from, or deficient
in, each of the emulated UNIX environments, see the source files
.Ar v1trap.c,
.Ar v7trap.c
and
.Ar bsdtrap.c
in the source directory for
.Nm apout.
You should also consult the file
.Ar LIMITATIONS
in the source directory for
.Nm apout.
.Sh SEE ALSO
The latest source for
.Nm apout
can be obtained via anonymous ftp at minnie.tuhs.org in the directory
pub/PDP-11/Sims/Apout. The directory pub/PDP-11/Sims/Apout/UnixBins
contains tar archives of a.out binaries from several versions of UNIX.
Information on PDP-11 UNIX can be found on the PUPS web page at
http://minnie.tuhs.org/PUPS/
.Sh HISTORY
The first version of
.Nm apout
appeared in 1995, and provided support for 6th and 7th Edition
UNIX binaries. In 1998/1999, support was added for 2.11BSD binaries.
In 1999/2000, support was added for 1st and 2nd Edition UNIX binaries.