home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / w3_diag / mapwin.arj / MAPWIN.DOC next >
Encoding:
Text File  |  1991-12-30  |  6.6 KB  |  184 lines
  1. Using MAPWIN
  2. ------------
  3.  
  4.     MAPWIN, written by Richard Smith (president of Phar Lap
  5. Software), is a program that makes it easy to see what API functions
  6. a Windows program uses, or what functions a dynamic-link library
  7. (DLL) or device driver provides.  Phar Lap generally uses this
  8. utility to determine what API functions need to be implemented in
  9. order to run a program under its 286|DOS-Extender environment.  You
  10. can use it to snoop around inside Windows, and uncover useful
  11. undocumented API functions.
  12.  
  13.     MAPWIN is a character-mode program that runs under DOS, the DOS
  14. box in Windows, or in OS/2 1.x.  
  15.  
  16.     To use MAPWIN, simply point it at a Windows executable file.  The
  17. output can be redirected to a file. For example:
  18.  
  19. C:\BIN>mapwin \windows\taskman.exe > taskman.log
  20.  
  21. C:\BIN>mapwin \windows\system\user.exe > user.log
  22.  
  23. C:\BIN>mapwin \windows\system\system.drv > system.log
  24.  
  25.     MAPWIN will produce a list of the executable's exports, and
  26. another list of its imports, plus some other information. For
  27. example:
  28.  
  29. ;-----------------------------------------------------------
  30.  
  31. C:\BIN>mapwin \windows\system\system.drv
  32. MAPWIN: 4.0 -- Copyright (C) 1986-91 Phar Lap Software, Inc.
  33.  
  34. Dump of the .DLL file -- \windows\system\system.drv
  35.  
  36. Header information
  37.  
  38. Target operating system................Windows
  39. Initial CS:IP..........................#0001:01F2
  40. DLL initialization.....................One time
  41. Automatic data segment.................None
  42.  
  43. DLLs called by this program
  44.  
  45.    KERNEL
  46.  
  47. Exported entry points
  48.  
  49.    WEP (system.10)
  50.    A20_PROC (system.20)
  51.    CREATESYSTEMTIMER (system.2)
  52.    INQUIRESYSTEM (system.1)
  53.    SAVE80X87STATE (system.8)
  54.    KILLSYSTEMTIMER (system.3)
  55.    GET80X87SAVESIZE (system.7)
  56.    GETSYSTEMMSECCOUNT (system.6)
  57.    RESTORE80X87STATE (system.9)
  58.    ENABLESYSTEMTIMERS (system.4)
  59.    DISABLESYSTEMTIMERS (system.5)
  60.  
  61. Imported references
  62.  
  63.    __ROMBIOS (KERNEL.173)
  64.    ALLOCCSTODSALIAS (KERNEL.170)
  65.    NOHOOKDOSCALL (KERNEL.101)
  66.  
  67. ;-----------------------------------------------------------
  68.  
  69.    The imports are assigned names based on a table built into
  70. MAPWIN.EXE, which matches module.ordinal pairs (such as KERNEL.101
  71. above) with ASCII function names (such as NOHOOKDOSCALL above).
  72.  
  73.     The table built into MAPWIN can be overriden. MAPWIN does not
  74. "know" about all Windows 3.0 DLLs and device drivers; nor does it
  75. know about vendor-specific DLLs that come with many Windows
  76. applications; nor, of course, does it know about any new functions
  77. provided by Windows 3.1. MAPWIN can be extended by specifying an
  78. "import file" on the command line (you must give an exact path).  For
  79. example:
  80.  
  81. C:\BIN>mapwin @\pcmag\win30.imp \windows\taskman.exe
  82.  
  83.     An import files contains one or more lines such as the following:
  84.  
  85. -IMPORT GETTABBEDTEXTEXTENT=USER.197
  86. -IMPORT CASCADECHILDWINDOWS=USER.198
  87. -IMPORT TILECHILDWINDOWS=USER.199
  88. -IMPORT OPENCOMM=USER.200
  89.  
  90.     MAPWIN.ZIP comes with the file WIN30.IMP, which includes all
  91. exports from COMM.DRV, GDI.EXE, KRNL386.EXE (KERNEL module),
  92. KEYBOARD.DRV, LZEXPAND.DLL, MOUSE.DRV, SOUND.DRV, SYSTEM.DRV,
  93. USER.EXE, VGA.DRV (DISPLAY module), WINDEBUG.DLL, and WINMEM32.DLL.
  94. In addition, undocumented API functions are marked with @@ to make
  95. them stand out and to make it easy for you to search for them, using
  96. a tool such as grep or DOS sort. Obscure (but documented somewhere!)
  97. functions are marked with @; finally, the GetProcAddress() function
  98. is marked with $$ to remind you that, if a program calls this
  99. run-time dynamic linking function, then static examination of the
  100. file probably won't reveal all the API functions that it uses.  Using
  101. WIN30.IMP, MAPWIN output will look something like this:
  102.  
  103. Imported reference(s)
  104.  
  105.    ARRANGEICONICWINDOWS (USER.170)
  106.    CASCADECHILDWINDOWS@@ (USER.198)
  107.    DIALOGBOX (USER.87)
  108.    GETDESKTOPHWND@ (USER.278)
  109.    GETDLGITEM (USER.91)
  110.    GETPROCADDRESS$$ (KERNEL.50)
  111.    GETSYSTEMMETRICS (USER.179)
  112.    GETTASKFROMHWND@ (USER.117)
  113.    INITAPP@ (USER.5)
  114.    INITTASK@ (KERNEL.91)
  115.    ISWINOLDAPTASK@@ (KERNEL.158)
  116.    SWITCHTOTHISWINDOW@@ (USER.172)
  117.    TILECHILDWINDOWS@@ (USER.199)
  118.    UNLOCKSEGMENT (KERNEL.24)
  119.    WAITEVENT@ (KERNEL.30)
  120.  
  121.     Here, functions such as CascadeChildWindows() and
  122. IsWinOldApTask() are marked with @@ because they are undocumented.
  123. The functions GetDesktopHwnd() and GetTaskFromHwnd() are given only a
  124. single @ because, while undocumented, they are identical to
  125. documented functions (GetDesktopWindow() and GetWindowTask()) and are
  126. therefore uninteresting. Functions such as InitApp() and InitTask()
  127. are also given a single @ because, while not listed in WINDOWS.H or
  128. in the Microsoft Windows _Programmer's Reference_, they _have_ been
  129. documented by Microsoft as part of "Open Tools".
  130.  
  131.     To find all undocumented functions (assuming you have egrep from
  132. one of the collections of Unix-compatible tools such as the MKS
  133. Toolkit or the Thompson Toolkit):
  134.  
  135. C:\BIN>egrep @@ win30.imp
  136.  
  137.     To find all quasi-documented functions:
  138.  
  139. C:\BIN>egrep [^@]@ win30.imp
  140.  
  141.     If you don't have grep, egrep, or fgrep, you can always use
  142. FIND from DOS:
  143.  
  144. C:\BIN>\dos\find "@" win30.imp
  145.  
  146.     For the statistics collectors among you, it might be interesting
  147. to note that 934 Windows 3.0 functions are listed in WIN30.IMP, of
  148. which 248 are designated as undocumented, and an additional 88 are
  149. designated as quasi-documented.  
  150.  
  151.     In addition to WIN30.IMP, you can create your own *.IMP files by
  152. using the MAPWIN -IMPMAKE switch.  When Windows 3.1 becomes
  153. available, for instance, you can produce a WIN31.IMP file by running
  154. MAPWIN -IMPMAKE on all its EXEs, DLLs, DRVs, and so on (make sure you
  155. don't miss any!):
  156.  
  157. C:\BIN>for %f in (\win31\system\*.exe) do mapwin -impmake %f >> win31.imp
  158.  
  159. C:\BIN>for %f in (\win31\system\*.dll) do mapwin -impmake %f >> win31.imp
  160.  
  161. C:\BIN>for %f in (\win31\system\*.drv) do mapwin -impmake %f >> win31.imp
  162.  
  163.     Naturally, you can produce additional *.IMP files for the vendor-
  164. specific DLLs provided with any applications you use, for Windows
  165. Multimedia, Pen Windows, and so on.
  166.  
  167.     You can specify multiple *.IMP files on the MAPWIN command line,
  168. like so:
  169.  
  170. C:\BIN>mapwin @win30.imp @phoo.imp @bar.imp \baz\zar\quux.exe
  171.  
  172.     Once you have run MAPWIN on a program, you may want a quick way
  173. to see what undocumented or quasi-documented calls it's making.  Just
  174. use the DOS pipe | to put MAPWIN together with GREP or FIND:
  175.  
  176. C:\BIN>mapwin @\pcmag\win30.imp \phoo\bar\someprog.exe | \dos\find "@@"
  177.  
  178.     MAPWIN is extracted from a far more extensive Phar Lap utility.
  179.  
  180. -- Andrew Schulman
  181.    CIS 76320,302
  182.    Internet: andrew@pharlap.com
  183.  
  184.