diff options
Diffstat (limited to 'systems/msdos/tx/src/spawno.doc')
-rw-r--r-- | systems/msdos/tx/src/spawno.doc | 486 |
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 + |