home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / jed098-4.zip / jed / bin / emxrt.doc
Text File  |  1996-11-12  |  44KB  |  1,233 lines
  1. ===============================================================================
  2. emxrt.doc    emx 0.9c FIX 02     USER'S GUIDE TO THE EMX RUNTIME    11-Nov-1996
  3. ===============================================================================
  4.                                      Copyright (c) 1990-1996 by Eberhard Mattes
  5.  
  6. Table of Contents
  7. =================
  8.  
  9. 1     Introduction to the User's Guide to the emx Runtime
  10. 1.1     Hardware requirements
  11. 1.2     Files included in the emx runtime package
  12. 2     License
  13. 3     Installing the emx runtime package under OS/2
  14. 3.1     Summary for impatient OS/2 users
  15. 3.2     Detailed instructions for OS/2 users
  16. 4     Installing the emx runtime package under DOS
  17. 4.1     Summary for impatient DOS users
  18. 4.2     Detailed instructions for DOS users
  19. 5     Environment variables (OS/2 and DOS)
  20. 5.1     Environment variables (DOS)
  21. 6     DOS Notes
  22. 6.1     General notes
  23. 6.2     Emergency exit
  24. 6.3     Using rsx instead of emx
  25. 7     emx options
  26. 7.1     emx options (OS/2)
  27. 7.2     emx options (DOS)
  28. 8     The emxstack tool
  29. 9     The emxupd tool
  30. 9.1     Replacing a DLL
  31. 9.2     Deleting a DLL
  32. 9.3     Unpacking DLLs from a ZIP file and installing them with emxupd
  33. 10    Troubleshooting
  34. 10.1    Warning message `WARNING: emx 0.9c or later required'
  35. 10.2    unzip.exe says `cannot create emx/dll/emx.dll'
  36. 10.3    emx.dll cannot be deleted, renamed or overwritten
  37. 10.4    Error message `SYS1804: The system cannot find the file EMX.'
  38. 10.5    Error message `rsx not found, DPMI not supported by emx'
  39. 10.6    Error message `emx.dll: Stack size too small...'
  40. 10.7    DOS message `Sector not found'
  41. 11    emx messages
  42. 11.1    emx messages (OS/2)
  43. 11.2    emx messages (DOS)
  44. 12    Obtaining the complete emx package
  45. 13    The author of emx
  46.  
  47.  
  48. 1 Introduction to the User's Guide to the emx Runtime
  49. =====================================================
  50.  
  51. This is the documentation for the emx runtime package.  The emx
  52. runtime is an environment for 32-bit programs under OS/2 2.x, OS/2 3.x
  53. (OS/2, in short), MS-DOS, and PC-DOS (DOS, in short) on machines with
  54. a 386 CPU (or one of its successors).
  55.  
  56. Under OS/2, you can view the .inf version of this document by typing
  57.  
  58.     view \emx\book\emxrt
  59.  
  60. If you add \emx\book to the BOOKSHELF environment variable, you can
  61. type
  62.  
  63.     view emxrt
  64.  
  65. to view that on-line book.
  66.  
  67.  
  68. 1.1 Hardware requirements
  69. -------------------------
  70.  
  71. emx requires an 80386 CPU (80386DX, 80386SX, i486, or later)
  72.  
  73.  
  74. 1.2 Files included in the emx runtime package
  75. ---------------------------------------------
  76.  
  77. The emx runtime package includes the following files:
  78.  
  79.   \emx\bin\emx.exe              emx runtime for DOS
  80.   \emx\bin\emxbind.exe          Tool for modifying emx programs (DOS and OS/2)
  81.   \emx\bin\emxfpemu             Emulator for numeric coprocessor (DOS)
  82.   \emx\bin\emxl.exe             emx loader (used by emxbind)
  83.   \emx\bin\emxload.exe          Server for keeping OS/2 programs in memory
  84.   \emx\bin\emxrev.cmd           Tool for displaying emx revisions (OS/2)
  85.   \emx\bin\emxstack.exe         Tool for fixing the stack size of old programs
  86.   \emx\bin\emxupd.exe           Tool for updating a DLL which is in use
  87.   \emx\bin\emxuzdll.cmd         Unpack DLLs and install them with emxupd.exe
  88.   \emx\book\emxrt.inf           The text you are looking at (VIEW version)
  89.   \emx\dll\emx.dll              emx runtime for OS/2
  90.   \emx\dll\emxio.dll            Hardware port I/O under OS/2
  91.   \emx\dll\emxlibc.dll          Forwarder DLL to emxlibcm.dll (OS/2)
  92.   \emx\dll\emxlibcm.dll         Multithread C library (OS/2)
  93.   \emx\dll\emxlibcs.dll         Single-thread C library (OS/2)
  94.   \emx\dll\emxwrap.dll          Interface to 16-bit OS/2 functions (OS/2)
  95.   \emx\doc\COPYING              GNU General Public License
  96.   \emx\doc\COPYING.EMX          emx copyright information
  97.   \emx\doc\emxrt.doc            The text you are looking at (text version)
  98.   \emx\etc\termcap.dat          Terminal data base for termcap-based programs
  99.   \emx\etc\emclibcm.map         Map file for emxlibcm.dll
  100.   \emx\etc\emclibcm.tdf         Trace definition file for emxlibm.dll
  101.   \emx\etc\emclibcs.map         Map file for emxlibcs.dll
  102.   \emx\etc\emclibcs.tdf         Trace definition file for emxlibs.dll
  103.   \emx\etc\trc00f8.tff          Trace format file for emxlibcs.dll
  104.   \emx\etc\trc00f9.tff          Trace format file for emxlibcm.dll
  105.  
  106. The .map, .tdf, and .tff files are used for debugging.  They are
  107. included in emxrt.zip to keep them in sync with the DLLs.
  108.  
  109.  
  110. 2 License
  111. =========
  112.  
  113. emx is free software; you can redistribute it and/or modify it under
  114. the terms of the GNU General Public License as published by the Free
  115. Software Foundation; either version 2, or (at your option) any later
  116. version.
  117.  
  118. emx is distributed in the hope that it will be useful, but WITHOUT ANY
  119. WARRANTY; without even the implied warranty of MERCHANTABILITY or
  120. FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  121. for more details.
  122.  
  123. You should have received a copy of the GNU General Public License
  124. along with emx; see the file COPYING.  If not, write to the Free
  125. Software Foundation, 59 Temple Place - Suite 330, Boston, MA
  126. 02111-1307, USA.
  127.  
  128. See \emx\doc\COPYING.EMX and \emx\doc\COPYING for details.
  129.  
  130. Please note that source code for parts of the contents of emxrt.zip is
  131. contained in emxfix02.zip.
  132.  
  133.  
  134. 3 Installing the emx runtime package under OS/2
  135. ===============================================
  136.  
  137.  
  138. 3.1 Summary for impatient OS/2 users
  139. ------------------------------------
  140.  
  141. 1.  If you are using Siegfried Hanisch's ScreenSaver, either upgrade
  142.     to version 2.6 or disable ScreenSaver
  143.  
  144. 2.  Add \emx\dll to LIBPATH (always use the latest copy of the .dll
  145.     files!)
  146.  
  147. 3.  Add \emx\bin to PATH
  148.  
  149. 4.  Reboot
  150.  
  151.  
  152. 3.2 Detailed instructions for OS/2 users
  153. ----------------------------------------
  154.  
  155. emx does not work with OS/2 1.x and in DOS mode of OS/2.
  156.  
  157. Before changing config.sys, make a backup copy of that file!
  158.  
  159. emx 0.9c breaks some versions of Siegfried Hanisch's ScreenSaver.
  160. Either upgrade to version 2.6 or disable ScreenSaver before installing
  161. emx 0.9c.  Otherwise, your system will freeze.
  162.  
  163. The emx runtime is implemented as a set of dynamic link libraries
  164. under OS/2:
  165.  
  166. emx.dll
  167.         emx run-time support for OS/2
  168.  
  169. emxio.dll
  170.         access to hardware ports for emx programs under OS/2
  171.  
  172. emxlibc.dll
  173.         forwarder DLL to emxlibcm.dll for existing applications that
  174.         use emxlibc.dll (which has been renamed to emxlibcm.dll)
  175.  
  176. emxlibcm.dll
  177.         multithread emx C library
  178.  
  179. emxlibcs.dll
  180.         single-thread emx C library
  181.  
  182. emxwrap.dll
  183.         32-bit wrappers for 16-bit OS/2 API functions
  184.  
  185. OS/2 looks for dynamic link libraries in the directories listed in the
  186. LIBPATH statement of your config.sys file.  Note that LIBPATH is not
  187. an environment variable!
  188.  
  189. At any time, at most one version of a dynamic link library is loaded.
  190. If there are different versions of a dynamic link library in the
  191. directories listed in the LIBPATH statement, the first one listed is
  192. loaded.  If you already have installed the emx dynamic link libraries,
  193. you should be careful to use the latest revision of those dynamic link
  194. libraries.  Newer emx dynamic link libraries work with older emx
  195. programs (however, you may have to apply emxstack), but newer emx
  196. programs don't work with older emx dynamic link libraries.  To find
  197. out about already installed emx dynamic link libraries, type
  198.  
  199.     cd \emx\bin
  200.     emxrev
  201.  
  202. If no emx dynamic link libraries are installed, no output is produced.
  203. If there are emx dynamic link libraries installed, the names and
  204. revision numbers are displayed, for instance
  205.  
  206.     EMX : revision = 30
  207.     EMXIO : revision = 30
  208.     EMXLIBC : revision = 30
  209.     EMXLIBCM : revision = 30
  210.     EMXLIBCS : revision = 30
  211.     EMXWRAP : revision = 30
  212.  
  213. Only directories listed in the LIBPATH statement are searched.  To
  214. find out the revision numbers of the dynamic link libraries of this
  215. package, type
  216.  
  217.     emxrev -d c:\emx\dll
  218.  
  219. if you have put the emx runtime package on drive C.  After running
  220. emxrev, you should quit the command processor by typing
  221.  
  222.     exit
  223.  
  224. to release the dynamic link libraries (they have been loaded by
  225. cmd.exe as emxrev is a REXX procedure).  Otherwise, you cannot rename,
  226. overwrite, or delete those files.  This also happens if one of the emx
  227. dynamic link libraries is currently used by a program.  If you get
  228. error message SYS0032, or the message
  229.  
  230.     error:  cannot create emx/dll/emx.dll
  231.  
  232. from unzip when unpacking emxrt.zip, use
  233.  
  234.     pstat /L
  235.  
  236. to find out about the dynamic link libraries used by the programs
  237. currently running.  Terminate all the programs using emx.dll,
  238. emxio.dll, emxlibc.dll, emxlibcm.dll, emxlibcs.dll, or emxwrap.dll.
  239. The command
  240.  
  241.     emxload -qw
  242.  
  243. will unload programs kept in memory by emxload.exe.
  244.  
  245. If that doesn't help, use emxuzdll to install the emx DLLs: Create a
  246. temporary directory and run emxuzdll in that directory, giving the
  247. path name of emxrt.zip and the path name of the emx DLL directory on
  248. the command line:
  249.  
  250.     mkdir \emxtmp
  251.     chdir \emxtmp
  252.     emxuzdll a:\emxrt.zip c:\emx\dll
  253.     chdir ..
  254.     rmdir emxtmp
  255.  
  256. This will replace the DLLs in c:\emx\dll with the DLLs in emxrt.zip
  257. even if the DLLs are in use.  The new versions of the DLLs become
  258. active as soon as the last process referencing them is terminated, or
  259. on the next reboot.  Therefore, you should reboot after running
  260. emxuzdll, otherwise you won't know if and when the new versions become
  261. active.  (Actually, you don't need a temporary directory, any
  262. directory not containing any DLL files will do.)
  263.  
  264. Either copy the latest revisions of the emx dynamic link libraries
  265. (that is, those with the highest revision numbers) to a directory
  266. directory listed in the LIBPATH statement of config.sys or, better,
  267. modify the LIBPATH statement to include the directory where the latest
  268. revisions of the emx dynamic link libraries can be found.
  269.  
  270. The directories of the LIBPATH statement are separated by semicolons.
  271. To add c:\emx\dll to the LIBPATH statement, append a semicolon -- if
  272. there is not yet a semicolon -- to the end of the line of config.sys
  273. that starts with
  274.  
  275.     LIBPATH=
  276.  
  277. Then, type the absolute name of the directory.  Example:
  278.  
  279.     LIBPATH=.;C:\OS2\DLL;C:\OS2\MDOS;C:\;C:\OS2\APPS\DLL;D:\EMX\DLL
  280.  
  281. Optionally, you can append a semicolon at the end.
  282.  
  283. Next, modify the line of config.sys starting with
  284.  
  285.     SET PATH=
  286.  
  287. to include the \emx\bin directory.  For instance, change
  288.  
  289.     SET PATH=C:\OS2;C:\OS2\SYSTEM;C:\OS2\MDOS\WINOS2;C:\OS2\INSTALL;
  290.     C:\;C:\OS2\MDOS;C:\OS2\APPS
  291.  
  292. to
  293.  
  294.     SET PATH=C:\OS2;C:\OS2\SYSTEM;C:\OS2\MDOS\WINOS2;C:\OS2\INSTALL;
  295.     C:\;C:\OS2\MDOS;C:\OS2\APPS;D:\EMX\BIN
  296.  
  297. As with LIBPATH, you have to put a semicolon between the path names
  298. and a trailing semicolon is optional.  Note that the last two examples
  299. are shown in two lines; in config.sys, however, the complete SET
  300. statement must be put into one line.
  301.  
  302. You might want to add \emx\book to the BOOKSHELF environment variable
  303. to simplify viewing the on-line documentation.  For instance, change
  304. the line
  305.  
  306.     SET BOOKSHELF=C:\OS2\BOOK;
  307.  
  308. of your config.sys file to
  309.  
  310.     SET BOOKSHELF=C:\OS2\BOOK;C:\EMX\BOOK
  311.  
  312. as with PATH, you have to put a semicolon between the path names and a
  313. trailing semicolon is optional.
  314.  
  315. Now, you should reboot to activate the changes to config.sys.  After
  316. booting, run
  317.  
  318.     emxrev
  319.  
  320. to verify that the latest revision of emx is now active.
  321.  
  322. If OS/2 says
  323.  
  324.     SYS1804: The system cannot find the file EMX.
  325.  
  326. when running an emx program, you have not correctly set the LIBPATH
  327. statement of config.sys.  See above for details.
  328.  
  329. When running an old program (which assumes that emx.dll creates a
  330. stack object if the stack size is too small), you will get an error
  331. message like
  332.  
  333.     emx.dll: Stack size too small.  Run
  334.       emxstack -f D:\BIN\PROGRAM.EXE
  335.     and try again.
  336.  
  337. Run emxstack as indicated by the error message to fix the stack size
  338. of the program.  If you can't (because you don't have write permission
  339. for the file), type
  340.  
  341.     set emxopt=-I
  342.  
  343. to make emx.dll ignore the problem.  However, the program will
  344. probably crash due to insufficient stack size.  Using the -I option is
  345. not recommended!
  346.  
  347.  
  348. 4 Installing the emx runtime package under DOS
  349. ==============================================
  350.  
  351.  
  352. 4.1 Summary for impatient DOS users
  353. -----------------------------------
  354.  
  355. 1.  Add \emx\bin to PATH or set EMX to point to \emx\bin\emx.exe
  356.  
  357. 2.  If you are using a memory manager which implements DPMI, enable
  358.     VCPI
  359.  
  360. 3.  Remove BREAK=ON from config.sys
  361.  
  362. 4.  Reboot
  363.  
  364.  
  365. 4.2 Detailed instructions for DOS users
  366. ---------------------------------------
  367.  
  368. emx programs for DOS come in two flavours: those which load emx.exe
  369. from a separate file and those which have the emx runtime emx.exe
  370. integrated in the executable file of the application program.
  371.  
  372. Before changing autoexec.bat and config.sys, make a backup copy of
  373. these files!
  374.  
  375. If you want to use a program which loads emx.exe, you have to put
  376. emx.exe into a directory which is listed in your PATH environment
  377. variable or you have to change the PATH environment variable (in
  378. autoexec.bat) to include the directory in which emx.exe can be found.
  379. For instance, if your autoexec.bat file contains the line
  380.  
  381.     path c:\dos;d:\bin
  382.  
  383. you have installed the emx runtime on drive D, you should modify that
  384. line to read
  385.  
  386.     path c:\dos;d:\bin;d:\emx\bin
  387.  
  388. You have to put a semicolon between the path names.
  389.  
  390. Alternatively, you can set an environment variable which directly
  391. points to the emx.exe executable.  If you use this method, your
  392. program can locate emx.exe more quickly.  If you have installed the
  393. emx runtime on drive D:, you should add the following line to your
  394. autoexec.bat file:
  395.  
  396.     set emx=d:\emx\bin\emx.exe
  397.  
  398. Note that a directory name is not sufficient -- you have to type the
  399. complete path name of the emx.exe file.
  400.  
  401. Programs of the second flavour, having emx.exe integrated, don't
  402. require \emx\bin added to the PATH environment variable or the EMX
  403. environment variable being set.  The program itself, however, may need
  404. changes to your autoexec.bat file.  See the documentation accompanying
  405. the program.  The following steps are required for both flavours of
  406. emx programs.
  407.  
  408. If you are using a memory manager (such as QEMM or EMM386 or 386max)
  409. which implements DPMI (DOS Protected Mode Interface), you have to
  410. change the invokation of that memory manager to enable VCPI as emx
  411. does not support DPMI.  See the documentation of your memory for
  412. details.  If your memory manager supports DPMI only (without VCPI),
  413. you have to remove or disable the memory manager.  Alternatively, you
  414. can use rsx, as indicated in section 6.3.  emx supports XMS and VCPI.
  415.  
  416. Examine your config.sys file: If there is a line
  417.  
  418.     BREAK=ON
  419.  
  420. in it, you should remove it as it causes trouble with emx and lots of
  421. other programs.
  422.  
  423. If and only if you are using an `Intel Inboard 386/PC' expansion board
  424. in your 8088-based PC, add the following line to autoexec.bat (it's
  425. very unlikely that you are using such an expansion board):
  426.  
  427.     set emxopt=-m3
  428.  
  429. If the swap file (used to swap memory pages to disk when running out
  430. of physical memory) should be in a specific directory or on a specific
  431. disk drive, set the EMXTMP environment variable in autoexec.bat.
  432. Example:
  433.  
  434.     set emxtmp=c:\tmp
  435.  
  436. Now, you should reboot to activate the changes to config.sys and
  437. autoexec.bat.
  438.  
  439.  
  440. 5 Environment variables (OS/2 and DOS)
  441. ======================================
  442.  
  443. The operation of emx and emx programs is controlled by several
  444. environment variables.  You might have to set one or more of the
  445. following environment variables:
  446.  
  447. INIT    used by termcap to find termcap.dat
  448.  
  449. TERM    used by termcap to define the terminal type
  450.  
  451. EMXETC  used by termcap to find termcap.dat
  452.  
  453. EMXOPT  emx options (see below)
  454.  
  455. EMXSHELL
  456.         overrides the COMSPEC environment variable.  You can use this
  457.         to run an alternate command processor (shell) from emx
  458.         programs
  459.  
  460. EMXPATH
  461.         search path for programs (usually not relevant)
  462.  
  463. PATH    search path for program (used if EMXPATH fails)
  464.  
  465. TERMCAP
  466.         used by termcap to find termcap.dat
  467.  
  468.  
  469. 5.1 Environment variables (DOS)
  470. -------------------------------
  471.  
  472. EMX     path name of emx.exe, used by programs which are bound with
  473.         emxl.exe (the emx loader) instead of emx.exe.  Set EMX to
  474.         speed up loading of emx.exe or to load a specific version of
  475.         emx.exe
  476.  
  477. EMXTMP  directory for the swap file
  478.  
  479. TMP     used if EMXTMP is not set
  480.  
  481.  
  482. 6 DOS Notes
  483. ===========
  484.  
  485.  
  486. 6.1 General notes
  487. -----------------
  488.  
  489. - emx requires DOS 3.0 or later
  490.  
  491. - emx does not support DPMI
  492.  
  493. - emx does not support DESQview without VCPI (use QEMM-386 with
  494.   DESQview)
  495.  
  496. - If emx doesn't work under DESQview (especially if it displays the
  497.   message
  498.  
  499.       Nonmaskable interrupt (NMI)
  500.  
  501.   either set the protection level to 0 or use the WATCHDOG=0 option of
  502.   QEMM-386.
  503.  
  504. - emx supports VCPI
  505.  
  506. - emx supports XMS.  Do not use emx with himem.sys 2.06 or earlier.
  507.  
  508. - emx checks for XMS version number 2.00 or later and for XMS driver
  509.   revision 2.06 or later, as older himem.sys drivers don't work
  510.   correctly.  You can override this check by using the -O emx option
  511.   (for drivers using a different revision numbering scheme), but emx
  512.   may not work with your XMS driver, anyway.  Actually, emx has not
  513.   been tested with himem.sys 2.05; 2.04 fails, 2.06 works.
  514.  
  515. - emx supports vdisk.sys 3.3 and later and most other RAM disk drivers
  516.  
  517. - emx uses (or tries to use) all available memory, whether
  518.   conventional, extended, or expanded memory.  If there isn't enough
  519.   memory, emx will swap to disk.  The swap file will be created in the
  520.   directory given by the EMXTMP environment variable.  If EMXTMP is
  521.   not set, TMP will be used.  If both variables are not set, the swap
  522.   file will be created in the root directory of the current drive.
  523.  
  524. - If a program uses floating point instructions and no numeric
  525.   coprocessor (387) is installed, emx tries to load the FPU (floating
  526.   point unit) emulator emxfpemu.  That file is first sought in the
  527.   directory from which emx.exe was loaded (this does not apply if
  528.   emx.exe is bound to the executable), then in the current working
  529.   directory and the directories listed in the EMXPATH and PATH
  530.   environment variables.  If emxfpemu cannot be found, the program
  531.   will be aborted by signal SIGFPE.
  532.  
  533.  
  534. 6.2 Emergency exit
  535. ------------------
  536.  
  537. If the computer freezes while running emx, try hitting Ctrl-Break five
  538. times in one scond.  That will terminate emx (and all emx processes
  539. run by that instance of emx) unless it is blocked in a DOS call.  If
  540. blocked in a DOS call, emx will terminate after return from that DOS
  541. call.
  542.  
  543.  
  544. 6.3 Using rsx instead of emx
  545. ----------------------------
  546.  
  547. rsx is a DPMI-compliant DOS extender which is more or less compatible
  548. to emx.  Moreover, rsx contains a floating point emulator.  rsx is
  549. free software and has been written by Rainer Schnittker.  As of this
  550. writing, rsx is assumed to be available for anonymous ftp as
  551.  
  552.     ftp.uni-bielefeld.de: /pub/systems/msdos/misc/dpmigcc5.zip
  553.     ftp.leo.org:          /pub/comp/os/os2/gnu/emx+gcc/contrib/dpmigcc5.zip
  554.  
  555. If the emx loader emxl.exe finds a DPMI server but no VCPI server, it
  556. tries to run rsx.exe instead of emx.exe.  The RSX environment variable
  557. will be used instead of the EMX environment variable for locating
  558. rsx.exe.
  559.  
  560. To load rsx.exe instead of emx.exe even if there is a DPMI server and
  561. a VCPI server (for instance if you need the floating point emulation
  562. of rsx), set the EMX environment variable to point to rsx.exe.  Note
  563. that rsx needs a DPMI server.
  564.  
  565.  
  566. 7 emx options
  567. =============
  568.  
  569. You can customize emx by setting the EMXOPT environment variable.
  570. This environment variable contains a list of options, similar to
  571. command line options.  The options must be separated by at least one
  572. blank.  Example:
  573.  
  574.     set emxopt=-c -h40
  575.  
  576.  
  577. 7.1 emx options (OS/2)
  578. ----------------------
  579.  
  580. -c      Disable core dumps caused by signals and exceptions
  581.  
  582. -h#     Set OS/2 file handle limit to #.  The number # must be between
  583.         10 and 65536
  584.  
  585. -n      Suppress popups for exceptions.  As emx.dll displays an
  586.         appropriate error message and dumps core, popups are not
  587.         required
  588.  
  589. -q      All command line arguments passed to child processes will be
  590.         quoted unconditionally, that is, wildcard expansion and
  591.         response files won't work in child processes of processes for
  592.         which the -q option is in effect
  593.  
  594. -r*     Prepend drive letter * to absolute path names.  If a path name
  595.         starts with / but does not start with //, /dev/ or /pipe/, *
  596.         followed by a colon will be prepended.  If -rd has been given,
  597.         the file name \mydir\abc will be translated to d:\mydir\abc.
  598.         Note: this option can cause unexpected effects
  599.  
  600. -t*     Truncate file names to 8.3 format.  Each part of a pathname is
  601.         truncated to 8.3 format by taking the first 8 characters
  602.         before the dot and the first 3 characters after the dot.  This
  603.         is useful to compile programs on a FAT filesystem with minimal
  604.         changes.
  605.  
  606.         Without argument, -t enables truncation on all drives and for
  607.         UNC pathnames.
  608.  
  609.         The -t option takes an optional argument, listing the names of
  610.         the drives on which file names should be truncated.  The
  611.         special drive name `/' controls whether to truncate UNC
  612.         pathnames.  With `-tc/', for instance, file names on drive C
  613.         and UNC pathnames will be truncated.
  614.  
  615.         If the argument of the -t option is `-', truncation is
  616.         disabled for all drives and for UNC pathnames.  This is the
  617.         default setting.  If the argument starts with `-', truncation
  618.         is disabled on all drives listed.  With `-t -t-d', for
  619.         instance, UNC pathnames and file names on all drives except
  620.         drive D will be truncated.
  621.  
  622. -x      Don't suppress wildcard expansion and response files if the
  623.         `MKS Korn shell' method of passing command line arguments is
  624.         used
  625.  
  626. -E      Run debuggee in same session (window) as debugger
  627.  
  628. -I      Don't complain about programs having too small a stack size.
  629.         Without the -I option, emx.dll displays an error message for
  630.         those programs, telling how to run emxstack to fix the stack
  631.         size.  With the -I option, the program is run despite of the
  632.         problem.  However, the program will probably crash due to
  633.         insufficient stack size.  Using the -I option is not
  634.         recommended!
  635.  
  636. -K      Don't use DosKillThread.  Due to bugs in OS/2, DosKillThread
  637.         may cause problems.  emx.dll automatically avoids using
  638.         DosKillThread for OS/2 2.1 and older.  For OS/2 2.11 and
  639.         later, you can use the -K option to disable usage of
  640.         DosKillThread.  Currently, DosKillThread is not used by
  641.         emx.dll and this option does not have any effect.
  642.  
  643.  
  644. 7.2 emx options (DOS)
  645. ---------------------
  646.  
  647. -c      Disable core dumps caused by signals and exceptions
  648.  
  649. -d      Don't use extended memory
  650.  
  651. -e      Redirect the standard error handle (2) to standard output (1)
  652.  
  653. -h#     Set DOS file handle limit to #.  The number # must be between
  654.         10 and 65536.  This option is ignored for DOS versions earlier
  655.         than 3.30.  This option does not change the emx limit for the
  656.         number of files per process -- that limit is always 40
  657.  
  658. -m1     Running on Fujitsu FMR70 (not implemented yet)
  659.  
  660. -m2     Running on NEC PC-98 (not implemented yet)
  661.  
  662. -m3     Running on Intel Inboard 386/PC
  663.  
  664. -o      Send the register dump of an exception to stdout.  Without -o,
  665.         the register dump is sent to the CON device.  You need -o for
  666.         redirecting the register dump to a file.
  667.  
  668.         emx now creates a core dump file (named `core') instead of a
  669.         register dump.  Please keep that file in case the author of
  670.         the program needs it for debugging.
  671.  
  672. -q      All command line arguments passed to child processes will be
  673.         quoted unconditionally, that is, wildcard expansion and
  674.         response files won't work in child processes of processes for
  675.         which the -q option is in effect
  676.  
  677. -r*     Prepend drive letter * to absolute path names.  If a path name
  678.         starts with / but does not start with //, /dev/ or /pipe/, *
  679.         followed by a colon will be prepended.  If -rd has been given,
  680.         the file name \mydir\abc will be translated to d:\mydir\abc.
  681.         Note: this option can cause unexpected effects
  682.  
  683. -t*     Truncate file names to 8.3 format.  Each part of a pathname is
  684.         truncated to 8.3 format by taking the first 8 characters
  685.         before the dot and the first 3 characters after the dot.  This
  686.         is useful to compile programs on a FAT filesystem with minimal
  687.         changes.
  688.  
  689.         Without argument, -t enables truncation on all drives and for
  690.         UNC pathnames.
  691.  
  692.         The -t option takes an optional argument, listing the names of
  693.         the drives on which file names should be truncated.  The
  694.         special drive name `/' controls whether to truncate UNC
  695.         pathnames.  With `-tc/', for instance, file names on drive C
  696.         and UNC pathnames will be truncated.
  697.  
  698.         If the argument of the -t option is `-', truncation is
  699.         disabled for all drives and for UNC pathnames.  This is the
  700.         default setting.  If the argument starts with `-', truncation
  701.         is disabled on all drives listed.  With `-t -t-d', for
  702.         instance, UNC pathnames and file names on all drives except
  703.         drive D will be truncated.
  704.  
  705. -E      Don't check for 387 coprocessor.  Assume no coprocessor is
  706.         present
  707.  
  708. -O      Override XMS version check.  By default, emx checks for XMS
  709.         version number 2.00 or later and for XMS driver revision 2.06
  710.         or later, as older himem.sys drivers don't work correctly.
  711.         You can override this check by giving the -O option (for
  712.         drivers using a different revision numbering scheme), but emx
  713.         may not work with your XMS driver, anyway.  Actually, emx has
  714.         not been tested with himem.sys 2.05; 2.04 fails, 2.06 works
  715.  
  716. -V      Display emx version.  On program start, the emx version will
  717.         be displayed
  718.  
  719. -X      Disable usage of XMS memory.  Usage of XMS memory with VCPI is
  720.         a new feature of emx.  If this happens to cause trouble, use
  721.         the -X option.
  722.  
  723.  
  724. 8 The emxstack tool
  725. ===================
  726.  
  727. The emxstack tool is used for displaying and fixing the stack size.
  728. Old programs assume that emx.dll allocates a stack object if the stack
  729. size is too small.  As emx.dll no longer does this, the stack size of
  730. the programs must be fixed.
  731.  
  732.     emxstack <command> [<options>] <file>...
  733.  
  734. The following commands are available:
  735.  
  736. -c
  737.  
  738.     Check whether the stack size should be fixed.  For each file, if
  739.     the stack size is too small, a message will be displayed.  If the
  740.     stack size is big enough, no message will be displayed.
  741.  
  742. -d
  743.  
  744.     Display the stack size.  For each file, the stack size in KByte
  745.     will be displayed.
  746.  
  747. -f
  748.  
  749.     Fix the stack size.  For each file, the stack size is fixed if it
  750.     is too small.
  751.  
  752. -s<size>
  753.  
  754.     Set the stack size.  For each file, the stack size is set to
  755.     <size> KByte.
  756.  
  757. -u<size>
  758.  
  759.     Update the stack size.  For each file, the stack size is set to
  760.     <size> KByte if it less than <size> KByte.  If the stack size is
  761.     not less than <size> KByte, the stack size won't be changed.
  762.  
  763. The following options are available:
  764.  
  765. -p
  766.  
  767.     Act on all files in the PATH.  The command is applied to each file
  768.     in a directory listed in the PATH environment variable.  No file
  769.     names must be given on the command line.
  770.  
  771. -q
  772.  
  773.     Be quiet.  No messages will be displayed.  However, error messages
  774.     won't be suppressed.
  775.  
  776. -v
  777.  
  778.     Be verbose.  Display additional messages.
  779.  
  780. Example:
  781.  
  782.     emxstack -f *.exe
  783.  
  784.  
  785. 9 The emxupd tool
  786. =================
  787.  
  788. The emxupd tool can replace (and delete) DLLs which are currently in
  789. use.  (It can do so for EXE files also.)  The old version of the DLL
  790. stays in memory and in use for programs which currently use it until
  791. all applications which use that DLL terminate.  Then, the new DLL will
  792. be used.  Rebooting also switches to the new DLL.
  793.  
  794.  
  795. 9.1 Replacing a DLL
  796. -------------------
  797.  
  798. To replace a DLL, type
  799.  
  800.     emxupd <source_file> <target_path>
  801.  
  802. This command copies <source_file> to the directory or file
  803. <target_path>.  Examples:
  804.  
  805.     emxupd c:\tmp\emx.dll c:\emx\dll
  806.  
  807. This command copies c:\tmp\emx.dll to c:\emx\dll\emx.dll.
  808.  
  809.     emxupd abc.dll d:\dll\new.dll
  810.  
  811. This command copies abc.dll to d:\dll\new.dll.
  812.  
  813.  
  814. 9.2 Deleting a DLL
  815. ------------------
  816.  
  817. To delete a DLL, type
  818.  
  819.     emxupd -d <old_file>
  820.  
  821. where <old_file> is the path name of the DLL to delete.
  822.  
  823.  
  824. 9.3 Unpacking DLLs from a ZIP file and installing them with emxupd
  825. ------------------------------------------------------------------
  826.  
  827. To unpack all DLLs from a ZIP file and install them in a directory
  828. with emxupd, replacing DLLs even if they are in use, type
  829.  
  830.     emxuzdll <zip_file> <dll_dir>
  831.  
  832. where <zip_file> is the path name of the ZIP file to unpack the DLLs
  833. from and <dll_dir> is the directory where all the DLLs of the ZIP file
  834. should be put.  emxuzdll can be used only if there are no DLL files in
  835. the current directory.
  836.  
  837.  
  838. 10 Troubleshooting
  839. ==================
  840.  
  841. This section shows how to solve common problems involving the emx
  842. runtime.
  843.  
  844.  
  845. 10.1 Warning message `WARNING: emx 0.9c or later required'
  846. ----------------------------------------------------------
  847.  
  848. If this message appears, an out-of-date version of emx.dll is active.
  849. Make sure that the latest version of emx.dll is in a directory pointed
  850. to by the LIBPATH statement in your config.sys file.  Use
  851.  
  852.     emxrev -p c:\config.sys
  853.  
  854. to list all emx dynamic link libraries reachable by the LIBPATH
  855. statement of c:\config.sys (use the drive letter of your boot drive
  856. instead of c:).  To simplify things, you should keep only one version
  857. of each DLL.  Older programs work with newer emx DLLs, but not vice
  858. versa.
  859.  
  860.  
  861. 10.2 unzip.exe says `cannot create emx/dll/emx.dll'
  862. ---------------------------------------------------
  863.  
  864. This happens when you try to unpack emxrt.zip while a program is
  865. active which uses emx.dll.  Terminate all programs which use emx.dll
  866. and try again.  If you run emxrev, the command interpreter keeps
  867. emx.dll loaded until terminated.  Therefore, you should close all OS/2
  868. windows and full-screen sessions in which you have run emxrev.  All
  869. this also applies to emxlibcm.dll etc.
  870.  
  871.  
  872. 10.3 emx.dll cannot be deleted, renamed or overwritten
  873. ------------------------------------------------------
  874.  
  875. See the previous problem.
  876.  
  877.  
  878. 10.4 Error message `SYS1804: The system cannot find the file EMX.'
  879. ------------------------------------------------------------------
  880.  
  881. You have not correctly set the LIBPATH statement of config.sys,
  882. therefore emx.dll could not be found.
  883.  
  884.  
  885. 10.5 Error message `rsx not found, DPMI not supported by emx'
  886. -------------------------------------------------------------
  887.  
  888. The current version of emx cannot use DPMI.  Therefore, the loader
  889. tried to use rsx instead, but couldn't find rsx.  Remedy: install rsx
  890. or end the DPMI server (MS Windows).
  891.  
  892.  
  893. 10.6 Error message `emx.dll: Stack size too small...'
  894. -----------------------------------------------------
  895.  
  896. You tried to run an old program (which assumes that emx.dll creates a
  897. stack object if the stack size is too small).
  898.  
  899. Run emxstack as indicated by the error message to fix the stack size
  900. of the program.  If you can't (because you don't have write permission
  901. for the file), type
  902.  
  903.     set emxopt=-I
  904.  
  905. to make emx.dll ignore the problem.  However, the program will
  906. probably crash due to insufficient stack size.  Using the -I option is
  907. not recommended!
  908.  
  909.  
  910. 10.7 DOS message `Sector not found'
  911. -----------------------------------
  912.  
  913. DOS seems to display that message if a file is opened twice (perhaps
  914. one handle for reading, one for writing).  For instance, this happens
  915. when GCC runs out of temporary files.  Look for files named like
  916. cca00002, ccz00002 etc. (the digits may vary) in your temporary
  917. directory and delete them.
  918.  
  919.  
  920. 11 emx messages
  921. ===============
  922.  
  923.  
  924. 11.1 emx messages (OS/2)
  925. ------------------------
  926.  
  927. core dumped
  928.  
  929.     The program cannot continue due to a fatal error (exception).  An
  930.     image of the program's memory has been written to a file named
  931.     `core'.  Please keep that file in case the author of the program
  932.     needs it for debugging.
  933.  
  934. emx.dll: Stack size too small...
  935.  
  936.     You tried to run an old program (which assumes that emx.dll
  937.     creates a stack object if the stack size is too small).  You
  938.     should run emxstack to fix the stack size.
  939.  
  940. Invalid option in EMXOPT
  941.  
  942.     An option in the EMXOPT environement variable is not understood by
  943.     emx.
  944.  
  945. Invalid syscall function code
  946.  
  947.     The program run by emx has called an invalid system function.
  948.     Most likely, you're using an emx.dll which is out of date.
  949.  
  950. WARNING: emx 0.9c or later required
  951.  
  952.     The program requires emx.dll 0.9c or later.  However, an older
  953.     version of emx.dll is active.  Make sure that the latest version
  954.     of emx.dll is in a directory pointed to by the LIBPATH statement
  955.     in your config.sys file.  Use
  956.  
  957.         emxrev -p c:\config.sys
  958.  
  959.     to list all emx dynamic link libraries reachable by the LIBPATH
  960.     statement of c:\config.sys (use the drive letter of your boot
  961.     drive instead of c:).  To simplify things, you should keep only
  962.     one version of each DLL.  Older programs work with newer emx DLLs,
  963.     but not vice versa.
  964.  
  965.  
  966. 11.2 emx messages (DOS)
  967. -----------------------
  968.  
  969. Abnormal program termination
  970.  
  971.     The program received the SIGABRT signal.  The abort() function was
  972.     called or SIGABRT was raised.
  973.  
  974. Bad environment
  975.  
  976.     The program name could not be found in the environment segment or
  977.     the environment segment is longer than 32768 bytes.  This should
  978.     not happen in practice.
  979.  
  980. Cannot create swap file
  981.  
  982.     The swap file could not be created.  Remedy: make sure the swap
  983.     file can be created in the directory given by the EMXTMP (or TMP)
  984.     environment variable.  If EMXTMP and TMP are not set, emx will
  985.     create the swap file in the root directory of the current drive.
  986.  
  987. Cannot enable A20
  988.  
  989.     emx tried to enable address line A20 and failed.  Remedy: contact
  990.     the author.
  991.  
  992. Cannot enable A20 via XMS
  993.  
  994.     emx tried to enable address line A20 by calling the XMS driver.
  995.     Unfortunately, A20 couldn't be enabled.  Remedy: unknown.
  996.  
  997. Cannot open program file
  998.  
  999.     The program file given on the emx command line could not be found
  1000.     or opened.  Remedy: type the correct file name.  (This should not
  1001.     happen with bound programs.)
  1002.  
  1003. Cannot read program file
  1004.  
  1005.     An error occured while reading the program file.  Remedy: make
  1006.     sure the program file given on the emx command line is valid (this
  1007.     does not apply to bound programs).  Maybe some other program
  1008.     accesses that file.
  1009.  
  1010. core dumped
  1011.  
  1012.     The program cannot continue due to a fatal error (exception).  An
  1013.     image of the program's memory has been written to a file named
  1014.     `core'.  Please keep that file in case the author of the program
  1015.     needs it for debugging.
  1016.  
  1017. DPMI not supported
  1018.  
  1019.     The current version of emx cannot use DPMI.  Maybe some future
  1020.     version will do.  Remedy: end the DPMI server (MS Windows) or use
  1021.     rsx.
  1022.  
  1023. emx not found
  1024.  
  1025.     The emx loader (emxl.exe) failed to find emx.exe.  Make sure that
  1026.     emx.exe is in a directory listed in the PATH environment variable.
  1027.     Alternatively, you can set the EMX environment variable to the
  1028.     complete path name of emx.exe.
  1029.  
  1030. Exception ...
  1031.  
  1032.     The program run by emx tried to do something which is considered
  1033.     illegal by the processor or by emx.  Remedy: report to the
  1034.     supplier of the program.
  1035.  
  1036. Illegal moucall function
  1037.  
  1038.     The program run by emx has called an invalid system function.
  1039.     Remedy: report to the supplier of the program.
  1040.  
  1041. Illegal syscall function
  1042.  
  1043.     The program run by emx has called an invalid system function.
  1044.     Remedy: report to the supplier of the program.
  1045.  
  1046. Illegal viocall function
  1047.  
  1048.     The program run by emx has called an invalid system function.
  1049.     Remedy: report to the supplier of the program.
  1050.  
  1051. Invalid arguments for DOS function xx
  1052.  
  1053.     The program run by emx has used invalid arguments for a system
  1054.     function.  Remedy: report to the supplier of the program.
  1055.  
  1056. Invalid emx option
  1057.  
  1058.     An option in EMXOPT or set by emxbind is not understood by emx.
  1059.     Remedy: check EMXOPT.  Use emxbind -i to display the options set
  1060.     by emxbind.
  1061.  
  1062. Invalid program file
  1063.  
  1064.     The program file given on the emx command line (or bound to emx)
  1065.     is corrupt.  Remedy: reload the program from diskette.  If this
  1066.     doesn't help you should contact the supplier of the program.
  1067.  
  1068. Invalid special function code: xx
  1069.  
  1070.     The program run by emx has called an invalid system function.
  1071.     Remedy: report to the supplier of the program.
  1072.  
  1073. Linear address space exhausted
  1074.  
  1075.     The program run by emx uses far too much memory.  Remedy: complain
  1076.     to the author.
  1077.  
  1078. Nonmaskable interrupt (NMI) at xxxx:yyyyyyyy
  1079.  
  1080.     A nonmaskable interrupt occured.  Maybe this is due to a memory
  1081.     error.  Remedy: if you are using DESQview, either set the
  1082.     protection level to 0 or use the WATCHDOG=0 option of QEMM-386.
  1083.     Otherwise, run a program for testing memory.
  1084.  
  1085. Out of memory
  1086.  
  1087.     There isn't enough memory for running emx.  Remedy: remove some
  1088.     drivers and/or resident programs.  Or add memory to your machine.
  1089.  
  1090. Out of stacks
  1091.  
  1092.     emx ran out of local stacks.  Remedy: complain to the author.
  1093.  
  1094. Out of memory or swap space
  1095.  
  1096.     emx cannot write to the swap file because the disk is full.
  1097.     Remedy: make sure there is enough space on the drive used for the
  1098.     swap file.  Use the EMXTMP (or TMP) environment variable to tell
  1099.     emx where to create the swap file.  If neither EMXTMP nor TMP is
  1100.     set, emx will create the swap file in the root directory of the
  1101.     current drive.
  1102.  
  1103. Out of swap space
  1104.  
  1105.     emx cannot write to the swap file because the disk is full.
  1106.     Remedy: make sure there is enough space on the drive used for the
  1107.     swap file.  Use the EMXTMP (or TMP) environment variable to tell
  1108.     emx where to create the swap file.  If neither EMXTMP nor TMP is
  1109.     set, emx will create the swap file in the root directory of the
  1110.     current drive.
  1111.  
  1112. Process terminated by SIGINT
  1113.  
  1114.     You have stopped the program by hitting Ctrl-C or Ctrl-Break.
  1115.  
  1116. Process terminated by SIG...
  1117.  
  1118.     The program has been stopped due to a signal or exception.
  1119.     Usually, this indicates a fatal error in the program.
  1120.  
  1121. Program aborted
  1122.  
  1123.     You have aborted the program by answering `Abort' after a critical
  1124.     error had occured.
  1125.  
  1126. rsx not found, DPMI not supported by emx
  1127.  
  1128.     The current version of emx cannot use DPMI.  Therefore, the loader
  1129.     tried to use rsx instead, but couldn't find rsx.  Remedy: install
  1130.     rsx or end the DPMI server (MS Windows).
  1131.  
  1132. Swap file I/O error
  1133.  
  1134.     emx couldn't read or write the swap file.
  1135.  
  1136. This program does not run in DOS mode of OS/2
  1137.  
  1138.     DOS emulation of OS/2 doesn't support emx.  Remedy: boot DOS or
  1139.     run the program in a OS/2 window
  1140.  
  1141. This program requires an 80386 CPU
  1142.  
  1143.     You need an 80386DX, 80386SX, i486 or later CPU for running emx.
  1144.     Remedy: get another computer.
  1145.  
  1146. This program requires DOS 3.0 or later
  1147.  
  1148.     If emx is bound with an application program into one executable,
  1149.     DOS 3.0 or later is required for execution.
  1150.  
  1151. Too many processes
  1152.  
  1153.     emx supports up to 4 processes.  You tried to start 5 or more
  1154.     processes.
  1155.  
  1156. Unexpected interrupt
  1157.  
  1158.     This cannot happen.  Remedy: report to the author.
  1159.  
  1160. Unsupported VDISK.SYS version
  1161.  
  1162.     emx doesn't support the vdisk.sys device driver you are using.
  1163.     Remedy: remove VDISK.SYS or use a different version.  emx should
  1164.     work with vdisk.sys 3.3 or later.
  1165.  
  1166. Unsupported XMS version
  1167.  
  1168.     emx requires himem.sys 2.06 or later (older versions are too
  1169.     buggy).  Remedy: get a newer himem.sys.  If you are not using
  1170.     himem.sys, use the -O option of emx and tell the author whether
  1171.     this works or not.
  1172.  
  1173. Unusable interrupt vector mappings set by VCPI server
  1174.  
  1175.     The configuration of the VCPI server (EMS driver) is illegal.
  1176.     Remedy: read the manual of the EMS driver.
  1177.  
  1178. Use emxbind
  1179.  
  1180.     You tried to run emxl.exe, which doesn't make sense.  emxl.exe is
  1181.     designed to be bound into an executable file by emxbind.
  1182.  
  1183. Virtual mode not supported without VCPI
  1184.  
  1185.     A VCPI server is required to run emx if the CPU is in virtual
  1186.     mode.  You will get this message if you're using an EMS driver
  1187.     (EMS emulator) which doesn't support VCPI or if you have disabled
  1188.     EMS.  Remedy: remove the EMS driver, use an EMS driver which
  1189.     supports VCPI or enable EMS if it has been disabled (for instance,
  1190.     remove the NOEMS keyword from the command line of the EMS driver).
  1191.  
  1192. Wrong emx version
  1193.  
  1194.     The version of emx.exe does not match the version the program was
  1195.     compiled for.  Remedy: use the copy of emx.exe that comes with the
  1196.     program.  If you are using different programs which need different
  1197.     versions of emx.exe, use the EMX environment variable to set the
  1198.     path name of the correct version of emx.exe before running a
  1199.     program which requires a version different from the default
  1200.     emx.exe.  You can also use emxbind -u to put the correct version
  1201.     of emx.exe into the executable files.
  1202.  
  1203.  
  1204. 12 Obtaining the complete emx package
  1205. =====================================
  1206.  
  1207. emx is available for anonymous ftp on
  1208.  
  1209.     ftp.leo.org:          /pub/comp/os/os2/gnu/emx+gcc
  1210.     ftp-os2.cdrom.com:    /pub/os2/lang/emx09c
  1211.     ftp-os2.nmsu.edu:     /os2/unix/emx09c
  1212.     src.doc.ic.ac.uk:     /pub/packages/os2/32bit/unix/emx09c
  1213.  
  1214.  
  1215. 13 The author of emx
  1216. ====================
  1217.  
  1218. The author of emx is
  1219.  
  1220.     Eberhard Mattes
  1221.     Teckstrasse 81                                      (TeX: Teckstra\ss e)
  1222.     D-71696 Moeglingen                                  (TeX: M\"oglingen)
  1223.     Germany
  1224.  
  1225. Internet: mattes@azu.informatik.uni-stuttgart.de  (subject to change)
  1226.  
  1227. No telephone calls please!  It must be stressed that the author does
  1228. not reply to letters if you don't include return postage
  1229. (international postal reply coupon if you are outside Germany) and a
  1230. self-addressed envelope.
  1231.  
  1232. --------------------------- END OF EMXRT.DOC --------------------------------
  1233.