From: sandmann AT clio DOT rice DOT edu (Charles Sandmann)
Message-Id: <10301200055.AA27206@clio.rice.edu>
Subject: src/stub/stubdocs.txi
To: djgpp-workers AT delorie DOT com (DJGPP developers)
Date: Sun, 19 Jan 2003 18:55:21 -0600 (CST)
X-Mailer: ELM [version 2.5 PL2]
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Reply-To: djgpp-workers AT delorie DOT com

New file; included by ../utils/utils.tex

I will also be doing similar items for dxegen (in ../dxe)
and, symify, edebug32, fsdb (in ../debug)
and the base file to include them, provide nodes in Top, fix next/prev 
references.

Feel free to comment, wordsmith, edit - etc - but I am more interested in
getting *something* in the docs ASAP than getting it perfect.  Once it's
checked into CVS people can edit away on it :-)

@c -----------------------------------------------------------------------------
@node go32-v2, stubify, , Top
@chapter go32-v2

@code{go32-v2} is a utility which allows you to run unstubbed
@acronym{COFF} images.

With no command-line arguments, it prints the available physical and
virtual memory, much like @code{go32} did in v1.x.  It can run unstubified v2
@acronym{COFF} images, like this:
@smallexample
 go32-v2 myprog
@end smallexample

If you rename it to @file{go32.exe} and put on your @code{PATH}
before the v1.x @file{go32.exe}, it can also run v1 @acronym{COFF}
images, by loading the v1.x @code{go32} and letting it do the job.
With this setup, you can run v2 programs from v1.x programs, because
the v1.x program will load @code{go32-v2} (since it found it first on
the @code{PATH}) which knows how to run v2 images, instead the
original @code{go32} which cannot.

If you define the environment variable @env{GO32_V2_DEBUG}, @code{go32-v2}
will provide additional debugging output when it executes.

@c -----------------------------------------------------------------------------
@node stubify, stubedit, go32-v2, Top
@chapter stubify

Usage: @code{stubify} [@code{-v}] [@code{-g}] @file{files}

@code{stubify} is a utility that adds a DOS exectuable stub loader to the
front of a @acronym{COFF} image.  The input program may be @acronym{COFF}
or a stubbed @code{.exe}, and may be @acronym{COFF} with @code{.exe}
extension.  The resulting file will have @code{.exe} extension.

@strong{Options:}

@table @code

@item -v

Verbose mode. When given this switch, @code{stubify} prints verbose output
on the files processed.

@item -g

Generate mode. When given this switch, @code{stubify} will create an
image containing only the stub, which can be modified by
@code{stubedit} (@pxref{stubedit}) to point to a different existing
program in the same directory.  This is used to simulate links, so
@code{argv[0]} can be used to change program behavior or create a small
alias to the other program.

@end table

@c -----------------------------------------------------------------------------
@node stubedit, exe2coff, stubify, Top
@chapter stubedit

Usage: @code{stubedit} [@code{-h}] [@code{-v}] @file{file.exe} [@code{field=value} . . .]

@code{stubedit} is a utility that allows you to modify the DOS exectuable 
stub loader parameters.  These parameters allow you to set the default
stack size, real mode memory transfer buffer size, the @code{argv0} value,
and @acronym{DPMI} provider.

If @code{-v} is not specified and no fields are provided after the file name,
@code{stubedit} will enter an interactive mode which displays each field and
allow you to change the values individually.

@strong{Options:}

@table @code

@item -h

Help mode. When given this switch, @code{stubedit} prints internal help.

@item -v

View mode. When given this switch, @code{stubedit} will display the
current contents of the stub parameters instead of prompting to modify
them.

@item minstack=

Specify the minimum amount of stack space.  The value may be specified
in bytes, KBytes (with a K suffix), or MBytes (with a M suffix).

@item bufsize=

Specify the size of the convential memory transfer buffer size. The value 
may be specified in bytes or KBytes (with a K suffix).  The value must
be between 2 KByte and 63 KByte.

@item minstack=

Specify the minimum amount of stack space.  The value may be specified
in bytes, KBytes (with a K suffix), or MBytes (with a M suffix).


@item runfile=

Specify the base name of the file to actually run.  This is a string value
of 8 maximum characters, and it is only used when this is a stub pointing
to a different image (created by @code{stubify -g}).

@item argv0=

Specify the string to pass as file component of @code{argv[0]} (maximum of
16 characters).

@item dpmi=

Specify the name of the program to load to provide DPMI services if DPMI
is not currently available (maximum of 16 characters).  The stub will 
search for this file first in the directory of the image, then each 
directory in your PATH, and finally the current default directory.

@end table

@c -----------------------------------------------------------------------------
@node exe2coff, coff2exe, stubedit, Top
@chapter exe2coff

@code{exe2coff} is a utility that strips the DOS exectuable stub loader
from the front of @acronym{DJGPP} executable image and writes a
@acronym{COFF} image.  This would be used as the first step in replacing
the stub with a different stub.  For example:

@example
C:\> exe2coff myprog.exe
C:\> copy /b cwsdstub.exe+myprog mynewprog.exe
@end example

@c -----------------------------------------------------------------------------
@node coff2exe, , exe2coff, Top
@chapter coff2exe

@code{coff2exe} is an alias to the @code{stubify} utility (@pxref{stubify}).