
The material in ./undump is now unsupported (October 1990).

For almost all systems, undumped TeX is an inferior approach,
and the intrinsic machine dependency of these programs makes
them too costly to maintain with any promise of reliability.
We recommend that you bypass the use of undump, following the 
instructions in the primary TeX README file.

====================================================================== 

The contents of undump.tar.Z:

   undump/
       0UNSUPPORTED Makefile.BALANCE Makefile.PYR Makefile.SUN4 Makefile.SUN_V2 
       Makefile.SUN_V3 Makefile.SYS_V Makefile.VAX4_2 Makefile.VAX4_3 
       Setup.BALANCE Setup.PYR Setup.SUN4 Setup.SUN_V2 Setup.SUN_V3 Setup.SYS_V 
       Setup.VAX4_2 Setup.VAX4_3 scanargs.1 scanargs.c undump.1 undump.BALANCE.c 
       undump.PYR.c undump.SUN4.c undump.SUN_V2.c undump.SUN_V3 undump.SUN_V3.c 
       undump.SYS_V.c undump.VAX4_2.c undump.VAX4_3.c 
       Encore/
	   BU-README Makefile dumpcore.c dumpit.c undo.c undo.h undump.1 undump.c 
	   unexec.c unexec.c-dist unexec.diff 

====================================================================== 


Two Notes retired from the primary TeX README file, which may still 
be of interest to those using undump....

(1) Further Notes About Preloaded TeX
====================================================================== 

There is a hacky way, discovered by Pavel Curtis of Cornell, to get 
a TeX that starts immediately with a format file preloaded.  If you 
have compiled TeX with WEB-to-C, it may not be worth going through 
this step.  Be sure you read ./TeX3.1/Man-pages/tex.1 to see how TeX 
now works, before you decide to do this.  You should be aware that 
the following instructions were written for versions of TeX earlier 
than 2.993 (precursor to TeX 3.0). 

First, make sure that the environment variables TEXINPUTS, TEXFONTS, 
TEXFORMATS, and TEXPOOL are set up appropriately for your site.  If 
you've set things up as defined above, and are happy using the 
system-defined defaults, these four environment variables should not 
be defined (do an "unsetenv TEXINPUTS", etc., if you've defined 
them).  These environment variables contain directory paths, showing 
where to find the files refered to by the TeX "\input" and "\read" 
commands, where the fonts are, where the .fmt files are, and where 
the tex.pool file is.  When you make a preloaded version of TeX, the 
values associated with these variables in the environment of the 
person making the preloaded version get used to set the default 
paths in the preloaded version.  Later, if a person running the 
preloaded version hasn't defined these variables, the default paths 
that get used are those defined in the environment of the person 
making the preloaded version at the time the preloaded version was 
dumped.  See the file site.h for details of the format of these 
environment variables.  Also refer to the man page, ./TeX3.1/Man-
pages/tex.1.  (The .fmt file doesn't contain the environment 
variable information.  Hence, the effect of saying "virtex 
&formatfile" may differ from the effect of running a virtex with 
"&formatfile" preloaded.) 

Next, create the preloaded TeX by running virtex as follows::

                % virtex '&plain' xyxyxy
                This is TeX, C Version n.nnn (no format preloaded)
                ! I can't find file `xyxyxy.tex'.
                <*> &plain xyxyxy 
  
                Please type another input file name: ^\

That is, give the command line shown and, when it asks for a value 
for a new file name, hit your 'Quit' character (mine is ^\).  (Note: 
the space after '&plain' is necessary, otherwise you may get the 
message, "I can't find plain.fmt, using plain.fmt instead."  The 
results of this redundancy are not satisfactory.) 

Now type "undump tex virtex core". 

If one tried the obvious approach of just typing '&plain', the log 
file gets opened and put onto the chain of open files .  When the 
undumped TeX starts up again, it re-opens the log file, not 
realising that it's on the chain already, and creates a circularity 
in the linked list.  When it tries to flush the output the next 
time, it loops forever.  The use of a nonsense name for the input 
file prevents this, since it makes TeX wait to find out what name it 
should give to the log file.  If you left off the nonsense name on 
the command line, TeX would immediately open the texput.log file.  
This would also happen if you gave no arguments on the command line 
and answered virtex's "**" prompt with &plain but no nonsense name.  
We need a solution that lets us know when TeX has finished reading 
the .fmt file, but then pauses long enough to give us time to 
'Quit'.  The nonsense does the trick. 

=================================================================== 
^L


(2) Why Won't Undump Work On My System?
===================================================================

First, decide whether it really matters.  You might want to take a 
look at ./Unsupported/tex.script to see how undump was very 
successfully bypassed before the advent of TeX 2.993 (virtually == 
TeX 3.0).  Please be sure to read the current TeX man-page 
(./TeX3.1/Man-pages/tex.1) to see how the current TeX works.  We do 
recommend bypassing the use of undump.  If, however, you do not wish 
to do so, read on. 

To understand the workings of undump you must have a certain basic 
knowledge of two specific kinds of Unix file format: core and a.out.  
The core file, which is produced by several kinds of fatal execution 
error, can also be produced by a user-generated "quit" signal, sent 
from the keyboard by the control character "^\" on most Unix 
systems.  It is described in the Berkeley Unix manual, Section 5--
Special File formats (Manual page Core(5)), as the memory image of a 
terminated process.  

The commonest source for the initial state of this image is an 
"a.out" file.  (See the Manual page a.out(5) in the Berkeley Unix 
manual.)  This file is produced either by the assembler or by the 
link editor (from one or more *.o files).  It consists of a header 
and four other sections which guide the operating system to set up 
the initialized core image correctly.  "a.out" files are 
conventionally renamed at the time of compilation (by flags on the 
compilation command line) with the name of the program to be run.  
Both "initex" and "virtex" are actually "a.out" files, and can 
therefore be used in place of a "tex" file if you are willing to 
wait for format loading.  In some cases, as you will see, there is 
no choice. 

What you are trying to do with the undump system is to trap the 
virtex program at a point where it has completed a second stage of 
initialization and to dress the "core" memory image up with "a.out" 
headers so that it looks as if it came fresh from the link editor.  
You start by running virtex, and getting it to read in the plain.fmt 
file, then you force a dump of the "core" memory image.  The first 
requirement is that you be able to do that.  Clearly, if you cannot 
get a clean core image, you cannot do any of the other things.  

Once you have the core image, you must edit it to add the header 
structure to the beginning of the file, and possibly to provide 
certain other structures as well, then you can rename the result (in 
our case, we will call it tex or latex) and the operating system 
will accept it as if it were an "a.out" file.  This is what "undump" 
tries to do.  The line "undump tex virtex core" says, in effect, 
"create a file named 'tex' by taking the header information from the 
virtex `a.out' file and tacking it onto a copy of the core file just 
created." 

If only "a.out" format were stable across operating systems and 
versions of any given operating system, it would be relatively easy.  
But "a.out" format is one of the most system-dependent formats in 
the Unix world. You cannot be sure even from one version of an 
operating system to another that "a.out" format will remain stable, 
and you can be almost certain that the "a.out" format on any one 
vendor's machine will be different from that on all other machines.  
(It is not just perversity, there are some performance reasons as 
well.)  Ideally undump should be table driven, so that new "a.out" 
formats can be fed in easily, but we would first have to find a 
programmer who had access to fifteen different operating systems and 
had the stamina to keep from going mad while trying to deal with 
them. At present we have only a collection of unique system-
dependent versions of undump.  If none of our versions works on your 
machine, you probably have an operating system with yet another 
style of "a.out" and "core" file.  If you can manage to work out an 
undump for your machine, we would be delighted to add it to our 
collection, but we can't help you with technical information, 
because we have no access to anything but our Suns and Vaxen. 


==================== EOF ====================