summaryrefslogtreecommitdiff
path: root/systems/msdos/tx/src/spawno.doc
diff options
context:
space:
mode:
Diffstat (limited to 'systems/msdos/tx/src/spawno.doc')
-rw-r--r--systems/msdos/tx/src/spawno.doc486
1 files changed, 486 insertions, 0 deletions
diff --git a/systems/msdos/tx/src/spawno.doc b/systems/msdos/tx/src/spawno.doc
new file mode 100644
index 0000000000..8467c46d7e
--- /dev/null
+++ b/systems/msdos/tx/src/spawno.doc
@@ -0,0 +1,486 @@
+SPAWNO v4.13 12/12/91 disk/EMS/XMS/INT15 swapping replacement for spawn()
+(c) Copyright 1990,1991,1992 Ralf Brown. All Rights Reserved.
+
+
+-----------------
+LICENSE
+
+This document and the associated header file, libraries, and source and
+object modules may be freely copied provided that:
+ 1) all of the files are copied as a group (such as in a single
+ archive). See below for a list of files.
+ 2) the files are not modified in any way (including removal or
+ alteration of copyright notices or this license)
+ 3) no charge beyond a cost-recovery fee not to exceed $5, or a
+ general telecommunications connection fee, is made
+
+The source and/or object code comprising the public SPAWNO distribution
+may be incorporated at no charge into programs which are distributed or
+sold to others provided that:
+ 1) credit is given in the documentation. A mention such as
+ "This product uses the SPAWNO routines by Ralf Brown
+ to minimize memory use while shelling to DOS and
+ running other programs."
+ is sufficient.
+ 2) you drop me a line telling me that you are using SPAWNO and
+ in which product(s) you are using it (see addresses at the
+ end of this file). I'm interested in finding out how wide-
+ spread the use of SPAWNO becomes.
+
+
+-----------------
+DISCLAIMER
+
+Although both I and others have tested the code which comprises SPAWNO,
+it is entirely possible that SPAWNO may malfunction in environments or
+under circumstances in which it has not been tested. This code is
+provided AS IS, and the author disclaims any and all responsibility for
+damages (both consequential and incidental) resulting from the use or
+misuse of SPAWNO. Sole responsibility for determining the suitability
+of the code rests with the user.
+
+
+-----------------
+FILES
+
+The disk or archive you received should contain the following files:
+
+ SPAWNO.DOC this file
+ SPAWNO.H the header file providing prototypes for the functions
+ SPAWNx.LIB versions of the library for each of [T]iny, [S]mall,
+ [C]ompact, [M]edium, [L]arge, and [H]uge memory
+ models.
+ SPAWNTP.OBJ Turbo Pascal version of SPAWNO
+ SPAWNO.PAS Turbo Pascal unit encapsulating SPAWNO
+ SPAWN_MS.ZIP Microsoft C versions of compiler-specific functions
+ MSC.BAT replace Turbo C specific functions in libraries with
+ Microsoft C versions.
+ NOREPLAC.BAT remove replacements for the standard spawn..()
+ functions from the libraries.
+ SWAPTEST.C example program for testing
+ TEST.PAS example program for testing
+ SOURCE.ZIP archive containing partial source code for SPAWNO
+ _SPAWNO.H header file for recompiling library
+ *.C source for the spawn..() and spawn...o() functions
+ RULES.ASI shortened and modified Turbo C macro file
+ SPAWNO.INC include file for various important constants
+ SPAWNPTH.ASM source for the path search
+ CHECKEXT.ASM check for 'file', 'file.EXE', and 'file.COM'
+ SWAP_EMS.ASM support routines for swapping to EMS
+ SWAPLIST.ASM specify which swap types will be linked in
+ SPAWNENV.ASM make an environment block from an array of strings
+ SPAWNERR.ASM set _doserrno and errno
+ MAKEFILE
+
+
+-----------------
+WHAT'S NEW
+
+Changes/fixes from versions 4.00 to 4.10:
+ Now swaps to disk with non-NULL swap list in large-data memory models
+ Now correctly deletes swap file if child program changes directories
+ If the given program name is "FOO", and both "FOO" and either
+ "FOO.COM" and/or "FOO.EXE" exist in the same directory, it will
+ now execute either "FOO.COM" or "FOO.EXE" rather than "FOO", as
+ both version 4.00 and the Borland library functions do. To
+ execute "FOO", pass "FOO." rather than just "FOO" to the function.
+ Fixed bug which may have led to a partially corrupted environment
+ in a few circumstances
+Changes/fixes since version 4.10:
+ Fixed bug which caused the PSP to restore incorrectly after a spawn
+ when DS != SS.
+ Fixed bug introduced in v4.10 which caused a crash on return from the
+ child program if there was insufficient disk space for the swap
+ file.
+ Fixed error in va_start call in various *.C files. This problem
+ results in compile-time errors when compiling under BC++ in
+ certain modes (but the code compiled without warnings under
+ Turbo C 2.0).
+
+-----------------
+INSTALLATION
+
+If you are using Turbo C, Turbo C++, or Borland C++, simply dearchive
+the libraries and header file and place them where your compiler can
+find them. If you are using Microsoft C, dearchive SPAWN_MS.ZIP and
+then run the MSC batch file to replace the compiler-specific functions
+in the libraries with Microsoft C versions. Please do not run this
+batch file on your original copy of the libraries.
+
+If you are using Turbo Pascal, unarchive SPAWNTP.OBJ and SPAWNO.PAS.
+Compile SPAWNO.PAS and then add a USES SPAWNO; line to your program.
+After that you can call the function SPAWN() as desired. The
+distribution does not contain a pre-compiled version because .TPU
+files are not compatible between different versions of Turbo Pascal.
+
+
+-----------------
+INSTRUCTIONS
+
+As distributed, SPAWNO contains replacements for the standard spawn..()
+functions. You can use SPAWNO with absolutely no changes to your
+existing source code; however, you will probably want to call
+init_SPAWNO() from main(), and include SPAWNO.H for that source file.
+The initialization function takes two arguments: the first is a string
+containing a list of directories (separated by semicolons) in which to
+attempt to store the swap file when swapping to disk. The second
+specifies which swap devices to attempt to use; it may be either
+SWAP_ANY or the ORing or addition of any combination of SWAP_DISK,
+SWAP_EMS, SWAP_EXT, and SWAP_XMS (such as SWAP_DISK|SWAP_XMS). If you
+do not call init_SPAWNO(), the defaults are to attempt all swap devices
+and to store the swap file in the current directory when swapping to
+disk. init_SPAWNO() will set the swap file directory list to the first
+of the following to have a non-NULL, non-empty value: the environment
+variable SWAPDIR, the passed parameter, the environment variable TEMP,
+and the environment variable TMP. Note that init_SPAWNO is the only
+function in the library which uses these environment variables.
+
+After making the above change, recompile your existing code, but include
+the SPAWNO library in the link step. Note that SPAWNO does not support
+the P_OVERLAY spawn type--any calls using that argument should be
+replaced with the corresponding exec..() function. If a SPAWNO function
+is called with P_OVERLAY, it simply returns an error.
+
+For backwards compatibility with previous versions of SPAWNO, and for
+those who (for whatever reason) require the use of both the swapping and
+standard spawn..() functions, there is a second set of functions which
+take an explicit swap directory argument. To use them, include the
+header file SPAWNO.H. Then use the functions provided in this
+archive--spawnvo(), spawnlo(), spawnvpo(), etc--as you would the
+corresponding spawnv(), spawnl(), etc, except replace the first argument
+by a string containing the path where the swap file is to be stored.
+Note that the swap file path is required even when swapping to XMS, EMS,
+or plain extended memory, as SPAWNO will swap to disk anyway if there is
+not enough memory available.
+
+If you require the use of both the swapping and standard spawn..()
+functions, you will need to run the NOREPLAC.BAT batch file to remove
+the modules containing the replacements for the standard functions or
+arrange the linker command line such that SPAWNx.LIB is listed after the
+standard runtime library (for Turbo/Borland C users, the latter requires
+a separate TLINK command, as TCC/BCC places any libraries specified on
+the command line prior to the runtime library). Please do not run
+NOREPLAC on your original copy of the libraries, as the process is
+destructive and cannot be reversed.
+
+The spawn?p??() functions search for both .COM and .EXE files in the
+current directory and then in the pathed directories if no extension is
+given, but use the specified extension if present. If a full pathname
+is given to those functions, only the specified directory is searched.
+If both a path and an extension are given, only that specific file will
+be loaded. The other spawn..() functions check the current directory
+only. For all functions, if the specified filename does not contain an
+extension, SPAWNO will try the exact name given and the name with .COM
+and .EXE extensions. The extension-less name will be used if neither
+.COM nor .EXE exist. To force the use of the extensionless file even
+if a .COM or .EXE with the same name exists in the same directory,
+append a period, i.e. use "PROGRAM." rather than just "PROGRAM" as
+the name.
+
+When linking, you must include SPAWNx.LIB. A sample TCC line would be
+
+ tcc -mc <other-flags> sample spawnc.lib library.lib
+
+This results in 208 to 288 bytes remaining in memory (depending on swap
+type) while the spawned program executes. However, if you want to keep
+an interrupt hooked which might be invoked while spawned, you must set
+__spawn_resident large enough that *all* code and data which could be
+invoked by that interrupt is kept resident[1]. SPAWNO automatically
+deactivates INT 23h and INT 24h and restores them before returning to
+the caller unless __spawn_keepints is set to 1, so no extra work is
+required if those two are the only interrupts hooked by the program.
+
+----
+[1] Due to the segment layout used by C compilers, this option is probably
+ useful only when calling SPAWNO from assembly-language code (which can
+ localize such code and data near the start of the executable) or a
+ small program which uses a large amount of space in the far heap.
+
+
+-----------------
+ERROR CODES
+
+SPAWNO will return errno = ENOMEM (_doserrno = 8) if there is insufficient
+swap space available.
+
+
+-----------------
+ERROR MESSAGES
+
+SPAWNO: stack too small, retrying
+ SPAWNO did not correctly determine the stack requirements for
+ the system on which it is running, but was able to determine
+ that the specified minimum size is insufficient. On the retry,
+ the stack size is increased by one paragraph. Since SPAWNO
+ cannot always detect the problem, which would result in
+ memory chain corruption, you should increase the value of
+ __spawn_res_stack to prevent a recurrence of this error
+ message. For most systems, the default value of 4 paragraphs
+ will be sufficient.
+
+SWAP ERR
+ The resident stub detected an error while trying to reload the
+ main portion of the program and aborted. This may be due to
+ loading a TSR while swapped out or deleting the swap file.
+
+SPAWNO: error reloading program, aborting
+ The main portion of SPAWNO detected an error while attempting
+ to restore the remainder of the program to memory.
+
+
+-----------------
+LIMITATIONS
+
+After freeing all memory owned by the program except the initial (PSP)
+memory block and the environment, at least 384 bytes of conventional
+memory must be available. SPAWNO uses this for its temporary stack.
+This is of particular importance for the Turbo Pascal variant, because
+setting the maximum heap size to the available memory or greater will
+use up all RAM and prevent SPAWNO from allocating its temporary stack
+unless memory is fragmented or there is DOS 5 high memory available.
+
+SPAWNO may report insufficient memory even though the program to be
+executed would fit with up to 600 bytes to spare, due to the fact that
+part of the stack and all of the data used by DOS to start the program
+may be overwritten after the child program starts executing.
+
+Functions which pass an explicit environment attempt to allocate enough
+memory to build the environment block which is passed to the DOS EXEC
+function. If neither malloc() nor a DOS memory allocation request are
+successful, SPAWNO passes the original environment rather than the
+specified environment.
+
+As distributed, SPAWNO functions which do not take an explicit
+environment pointer pass the calling program's original environment to
+the child, rather than the current environment as modified by putenv().
+You may recompile SPAWNO to pass the current environment (see
+_SPAWNO.H); if you do so, the caveat discussed in the previous paragraph
+will apply to all of the spawn..() functions.
+
+
+-----------------
+SUPPORT
+
+Since I am not getting any money, I can't promise any support. Those
+who have purchased the complete source code will receive priority over
+those who haven't, but even they will only receive support to the
+extent that I have spare time....
+
+
+-----------------
+ACKNOWLEDGEMENTS
+
+Thanks to Gene McManus for testing the Microsoft versions of SPAWNO 3.0
+and 4.0.
+
+
+-----------------
+FUTURE PLANS
+
+The next release will drop support for DOS 2.x (which is now over
+eight years old) to reduce the code size and further reduce the size
+of the resident stub.
+
+
+-----------------
+SPAWNO versus THE COMPETITION
+
+Product: SPAWNO XSPAWN SWAP
+Version: 4.13 1.34 1.0
+Author: Ralf Brown Whitney Software Marty Del Vecchio
+Memory models: tsmclh tsmclh tsm
+Supported DOS vers: 2.0-5.0 2.1-5.0 3.0-5.0
+Code size [1]: 4.3-5.9K 4.4-9K 1.5K
+Resident stub (bytes): 208-288 1277+2*env 1.8K+env [2]
+Direct replacement for
+ spawn..(): yes yes no
+Use in existing code
+ without changes: yes no no
+Swap to disk: yes yes yes
+Swap to EMS: yes yes yes
+Swap to XMS: yes no no
+Swap to INT 15h ext: yes no no
+Multiple swap dirs: yes yes no
+Automatic unique swap
+ file naming: yes yes no
+May leave interrupts
+ hooked [3]: yes no yes
+Swaps DOS5 high memory: yes ? ?
+Free for any use: yes yes yes
+Source included: partial [4] yes yes
+
+Notes:
+[1] For both SPAWNO and XSPAWN, the amount added to the executable's
+ size depends on which functions of the library are called and which
+ of the additional C runtime library function that are called by
+ SPAWNO/XSPAWN would have been included anyway. SPAWNO's size may
+ be reduced by removing one or more swap types; the savings are
+ about 400 bytes per swap type (without EMS and non-XMS (INT 15h)
+ swapping, SPAWNO would add as little as 3.4K to the executable).
+
+[2] SWAP's resident size depends on the location of the object code
+ within the executable. The size reported here is the resident
+ size when SWAP immediately follows the Turbo C 2.0 startup code.
+ It will be larger in later versions of the Borland C compilers due
+ to the increasing size of the startup code.
+
+[3] For SPAWNO, enough of the program must be left in memory to keep all
+ interrupt handlers resident. XSPAWN has no provision for keeping
+ an interrupt handler resident unless swapping is disabled; it does
+ however permit selection whether a given interrupt handler will
+ automatically be restored to its original value or pointed at an
+ IRET instruction while swapped out. For SWAP, the swapper module
+ must be linked in after all code and data which might be accessed
+ by the interrupt handler(s).
+
+[4] Full SPAWNO source code is available for licensing. See ORDER.FRM for
+ details.
+
+
+-----------------
+Functions:
+ void init_SPAWNO(const char *swap_directories, int swap_types) ;
+
+ /* replacements for the standard functions */
+ int spawnv(int type, const char *name, const char **args) ;
+ int spawnvp(int type, const char *name, const char **args) ;
+ int spawnve(int type, const char *name, const char **args,
+ const char **env) ;
+ int spawnvpe(int type, const char *name, const char **args,
+ const char **env) ;
+ int spawnl(int type, const char *name, const char *argv0, ...) ;
+ int spawnlp(int type, const char *name, const char *argv0, ...) ;
+ int spawnle(int type, const char *name, const char *argv0, ...) ;
+ int spawnlpe(int type, const char *name, const char *argv0, ...) ;
+ int system(const char *command) ;
+ /* Note: the above functions return -1 (error) if 'type' is not */
+ /* P_WAIT */
+
+ /* setup function */
+ void init_SPAWNO(const char *overlay_path, int swap_types) ;
+ /* setup swapping options for the compatibility functions above */
+
+ /* SPAWNO-specific functions */
+ int spawnvo(const char *overlay_path, const char *name,
+ const char **args) ;
+ int spawnvpo(const char *overlay_path, const char *name,
+ const char **args) ;
+ int spawnveo(const char *overlay_path, const char *name,
+ const char **args,const char **env) ;
+ int spawnvpeo(const char *overlay_path, const char *name,
+ const char **args,const char **env) ;
+ int spawnlo(const char *overlay_path, const char *name,
+ const char *argv0, ...) ;
+ int spawnlpo(const char *overlay_path, const char *name,
+ const char *argv0, ...) ;
+ int spawnleo(const char *overlay_path, const char *name,
+ const char *argv0, ...) ;
+ int spawnlpeo(const char *overlay_path, const char *name,
+ const char *argv0, ...) ;
+ int systemo(const char *overlay_path, const char *command) ;
+ /* Note: the ..o() functions use only the current directory if */
+ /* overlay_path is NULL; the only function which checks */
+ /* the environment variables SWAPDIR and TEMP is */
+ /* init_SPAWNO(). */
+
+Global variables:
+ char __spawn_xms ;
+ Specify whether to use XMS memory for swapping (if available).
+ 0 = no, 1 = yes, default = 1
+ This variable is set by init_SPAWNO().
+ char __spawn_ems ;
+ Specify whether to use EMS memory for swapping (if available).
+ 0 = no, 1 = yes, default = 1
+ This variable is set by init_SPAWNO().
+ char __spawn_ext ; /* 0 = don't use non-XMS extended memory for swap */
+ Specify whether to use non-XMS extended memory (via INT 15h) for
+ swapping (if available). 0 = no, 1 = yes, default = 1
+ This variable is set by init_SPAWNO().
+ Note: SPAWNO should not be allowed to swap to extended memory if
+ running under a multitasker or task switcher, as other programs
+ would be able to grab the same memory used by SPAWNO to store the
+ swapped-out program. For this reason, SPAWNO automatically
+ disables swapping to non-XMS extended memory if it detects that
+ TopView, DESQview, or any other TopView API-compatible multi-
+ tasker is active, or the DOS 5 task switcher is loaded, or
+ MS Windows 3 is running in real or standard mode (enhanced mode
+ is not readily detectable from a program, unfortunately).
+ const char *pascal ___spawn_swap_dirs ;
+ Specify the list of directories in which to attempt to store
+ the swap file when swapping to disk. The directories are
+ separated by semicolons just as they would be in the PATH
+ environment variable. Default = NULL (same as ".": current
+ directory)
+ This variable is set by init_SPAWNO().
+ Note: SPAWNO will not swap to disk if this variable is set to an
+ empty string; if it is set to NULL, SPAWNO will use the default
+ directory list of ".".
+ char __spawn_keepints ;
+ Specify whether to deactivate INT 23h and INT 24h handlers by
+ temporarily restoring the vectors stored in the PSP.
+ 0 = no, nonzero = yes, default = 0
+ char __spawn_swap_UMA ;
+ Specify whether to swap out memory blocks in the upper memory
+ area (640K-1M). 0 = no, 1 = yes, default = 1
+ Note: This option only has an effect under MSDOS 5.0 or higher
+ with the line DOS=UMB or DOS=HIGH,UMB in CONFIG.SYS.
+ unsigned __spawn_resident ;
+ Specify the minimum number of paragraphs in the memory block
+ containing the PSP to keep resident while in the child program.
+ This value will be increased if necessary to be large enough to
+ hold the swapping code; it may also be increased slightly if it
+ causes the end of the shrunken PSP block to fall within a
+ specific section of SPAWNO's code. You may force the entire
+ main block to stay in memory by setting this variable to 0xFFFF;
+ however, the environment and any additional memory blocks
+ allocated by the program will still be swapped out. default = 0
+ Note: in addition to the PSP memory block, a small second block
+ is used for the stack needed by the swapping code (see below).
+ unsigned __spawn_res_stack ;
+ Specify the minimum number of paragraphs of the stack to keep
+ resident while in the child program. Default = 4, minimum = 2
+ (two paragraphs is only sufficient for bare DOS; TSRs which
+ hook INT 21h will increase the stack requirements, but four is
+ sufficient for most systems). SPAWNO attempts to compute the
+ necessary stack size, but this variable allows the computed
+ value to be overridden if necessary.
+
+External functions called by SPAWNO:
+ malloc() \ only when passing an array of environment strings
+ free() /
+
+External variables referenced by SPAWNO:
+ int errno ;
+ int _doserrno ;
+ unsigned int _psp ;
+ char **environ ; (only when passing an array of environment strings)
+
+Other:
+ This version of SPAWNO overwrites the PSP, so the commandline
+ will be lost unless it was copied before the first spawn().
+
+
+-----------------
+Functions (Turbo Pascal):
+ init_SPAWNO(swap_dirs : string ; swap_types : integer ;
+ min_resident : integer ; resident_stack : integer) ;
+ spawn(program_name : string ; arguments : string ;
+ envseg : integer) : integer ;
+
+Global Variables (Turbo Pascal):
+ spawno_error : integer ; (error code when spawn() returns -1)
+
+
+-----------------
+Send comments, bug reports, etc. to
+
+ Internet: ralf+@cs.cmu.edu
+ Fidonet: Ralf Brown 1:129/26.1 (or post a message to me on DR_DEBUG--I
+ have to route netmail outside Zone 1
+ via Internet -> Fidonet gateways, which
+ is not always reliable)
+or
+ Ralf Brown (this address will be valid until
+ 813 Copeland Way, Suite 26 at least November 1, 1993)
+ Pittsburgh, PA 15232
+