home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / sherlock / sherlock.doc next >
Encoding:
Text File  |  1992-11-23  |  17.0 KB  |  453 lines
  1. Sherlock - A Programmers helper.  
  2.  
  3.  
  4. Introduction
  5.  
  6. Trying to debug an application is usually a mystery.  Most of the time, the 
  7. debugging is at the developers computer where source code is available and 
  8. source level debuggers are able to quickly and easily locate problems. It is 
  9. relatively easy to find problems and correct them. At this point, there is
  10. little challenge.
  11.  
  12. Unfortunately, after a program has gone out the door, it is inevitable that a 
  13. problem occures at the end user's site.  If enough information is available, 
  14. some problems can be reproduced on your development machine.  Far too often
  15. an end user's configuration is not the same as yours and reproducing the
  16. problem is difficult if not impossible.  If a trace of what the program is
  17. currently doing at the customers site was available, then the developer would
  18. have a better idea of what went wrong and how to fix the problem.  What is
  19. needed is a way to debug the program at the end users site.  Giving the user
  20. access to the original source to run a debugger is usually not desireable.
  21. And, while reporting the linear address in OS/2 2.0 may make the end user
  22. feel good, it is useless to the developer since the machine configurations
  23. may be different and therefore will have different linear addresses.  This
  24. is where programmers have a real mystery.  Unfortunately, with so many of
  25. the pieces missing, the mystery usually cannot be solved.
  26.  
  27. Sherlock is a program to aid fellow  programmers in this remote diagnosis of
  28. program problems.  This is done through an interfaceless debugger.  Sherlock 
  29. will load the desired executable for debugging, start the program and then
  30. continue until an exception occures.  When an exception occures, the entire
  31. program state is dumped.  Each thread will have the current register thread
  32. dumped and then attempt to trace the stack back to the root node of the
  33. thread.
  34.  
  35.  
  36. Usage
  37.  
  38. Usage of SHERLOCK is simple, even for most end users.  The target program is 
  39. started as it would normally be started with the addition of listing Sherlock 
  40. ahead of the target application.  For example, if you wish to test the
  41. program xyz.exe with the parameters a b c.
  42.  
  43.        Normal:
  44.        xyz a b c
  45.  
  46.        With Sherlock:
  47.        Sherlock xyz a b c
  48.  
  49.  
  50. What will I get out of Sherlock?
  51.  
  52. Sherlock will generate is a log file of what the operator of a debugger would
  53. see.  Sherlock will try to load debugging information for each module which
  54. is loaded.  Sherlock's ability to decode debugging infomation is based upon
  55. loading a DLL to support each different debugging information format.
  56. Sherlock is capable of supporting many different debugging formats at the
  57. same time. Each module which is loaded by the target program will be sent to
  58. the support DLLs to ask whether it supports the debugging format of the
  59. module.  If it says yes, no other support DLLs will be asked whether they
  60. support the debugging format of the module.
  61.  
  62.  
  63. Sample Input
  64.  
  65. The following is the source to the program used to illistrate the output of Sherlock.
  66.  
  67.         /*
  68.         ** This is a test program for Sherlock.
  69.         */
  70.         #include <os2.h>
  71.  
  72.         int main(int argc, char **argv)
  73.         {
  74.                 DosOpen((PSZ)    0,     /* pszFileName */
  75.                         (PHFILE) 0,     /* pHFILE      */
  76.                                  0,     /* pulAction   */
  77.                                  0,     /* cbFile      */
  78.                                  0,     /* ulAttribute */
  79.                                  0,     /* fsOpenFlags */
  80.                                  0,     /* fsOpenMode  */
  81.                         (PEAOP2) 0);    /* peop2       */
  82.         }
  83.  
  84.  
  85. Sample Output
  86.  
  87. Sherlock will produce a log file named SHERLOCK.LOG in the current directory.
  88. Each execution of Sherlock will overwrite any existing log file.  The output
  89. will be as described below.
  90.  
  91.         Each exception is logged to the file.  Note that there are many types
  92.         of exceptions.  Some are diagnostic such as guard page exceptions.
  93.         Other exceptions are fatal, but can be recovered from.  Access
  94.         Violations while usually fatal can be recovered from.  For example,
  95.         C-Set/2 (Copyright IBM) inserts an exception handler which if not
  96.         overriden will print a register state dump.  If overridden, it is
  97.         possible to recover from the exception and continue program
  98.         execution.  SherLock will log ALL exceptions to the log file until
  99.         the program has terminated. The information is given as folows:
  100.  
  101.                 Exception #[0-3]        Debugger exception notification type.
  102.                 Addr: xxxxxxxx          Linear Address of the exception.
  103.                 Excpt: xxxxxxxx         Exception ID.
  104.                 Except #: ### Name      Exception ID and its name if known.
  105.                 Flags: ###              Exception flags.
  106.                 Next Rec: ###           Next exception record point.
  107.                 Exception in thread #   ID of the thread where the exception
  108.                                             occured.
  109.  
  110. Execption type 1 at 1a050179
  111.   Except #: c0000005  Access violation
  112.   Flags:    00000000
  113.   Next Rec: 00000000
  114.   Except Addr: 1a050179
  115.   Num Parms: 2
  116.   Except 0: 00000000
  117.   Except 1: ffffffff
  118. Exception in thread: 1
  119.  
  120.  
  121.         Each thread of execution within the executing program will have its
  122.         entire register set dumped.
  123.  
  124. Pid: 000000f0  Tid:    00000001
  125. Cmd:        0  Value:  00716668
  126. Addr: 0002294c  Buffer: 00037fd4
  127. Len:  00000024  Index:  00000000
  128. MTE:  0000030c
  129. EAX: 00172a80  EBX: 00000000  ECX: 00060010  EDX: 00060007
  130. ESP: 0002291c  EBP: 00022ae4  ESI: 00000000  EDI: 00000000
  131. EIP: 0000c0a0  EFLAGS: 00002206
  132.   Carry Parity Aux Zero Sign Trap IntE Dir OFlow IOPL Nested Resume
  133.   NC    PE      0  NE    0    0    1   DN  NO    2    0      0
  134. CSLim 1c000000  CSBase: 00000000  CSAcc: df  CSAttr: d0  CS:005b
  135. DSLim 1c000000  DSBase: 00000000  DSAcc: f3  DSAttr: d0  DS:0053
  136. ESLim 1c000000  ESBase: 00000000  ESAcc: f3  ESAttr: d0  ES:0053
  137. FSLim 00000031  FSBase: 00050030  FSAcc: f3  FSAttr: 00  FS:150b
  138. GSLim 00000000  GSBase: 00000000  GSAcc: 00  GSAttr: 00  GS:0000
  139. SSLim 1c000000  SSBase: 00000000  SSAcc: f3  SSAttr: d0  SS:0053
  140.  
  141.  
  142.         Stack Trace - EBP, EIP of the current thread given by the register
  143.         dump.  Base is the Base offset within the given module.  Rel is the
  144.         relative offset of EIP within the Object/Segment.  Object is the
  145.         Object/Segment number assigned by the linker.  Module is the module
  146.         where execution is currently executing.  These three items together
  147.         are what any developer needs to determine where the program is
  148.         currently executing.  For unsupported debugging modules, a Hi and
  149.         Lo function marker are also given.  These may be helpful or may not
  150.         since these are based upon the exported functions of a module.  If a
  151.         module only contians a few functions exported, then the function
  152.         markers will most likely be useless.
  153.  
  154. EBP:    00022ae4        EIP:    1a02c0a0
  155.   Base: 1a020000        Rel:    0000c0a0  Len:    00010000
  156.   Object: 00000002
  157.   Module:   C:\OS2\DLL\DOSCALL1.DLL
  158.   Size:     87884
  159.   Timestamp:Mon Nov 23 08:01:48 1992
  160.  
  161.   Lo Function: DOSREAD
  162.   Hi Function: DOSCOPY
  163.  
  164. EBP:    00022b14        EIP:    1a02a958
  165.   Base: 1a020000        Rel:    0000a958        Len:    00010000
  166.   Object: 00000002
  167.   Module:   C:\OS2\DLL\DOSCALL1.DLL
  168.   Size:     87884
  169.   Timestamp:Mon Nov 23 08:01:48 1992
  170.  
  171.   Lo Function: DOSREAD
  172.   Hi Function: DOSCOPY
  173.  
  174.  
  175.         This entry shows the result of using one of the debugging support
  176.         DLLs.  The function, source module and line number are therefore
  177.         accessable and dumped.
  178.  
  179. EBP:    00022b3c        EIP:    00010023
  180.   Base: 00010000        Rel:    00000023  Len:    00010000
  181.   Object: 00000001
  182.   Module:   C:\WORK\DEBUG\CATCH.EXE
  183.   Size:     18778
  184.   Timestamp:Sun Sep 27 00:08:00 1992
  185.  
  186.   Function: main
  187.   Source:   CATCH.C
  188.   Line:     9
  189.  
  190.  
  191.         This entry shows the same module as the above entry, but the area
  192.         where the stack traced back to does not have debugging information,
  193.         so the bounding functions are dumped.
  194.  
  195. EBP:    00022b58        EIP:      00010596
  196.   Base: 00010000        Rel:   00000596  Len:    00010000
  197.   Object: 00000001
  198.   Module:   C:\WORK\DEBUG\CATCH.EXE
  199.   Size:     18778
  200.   Timestamp:Sun Sep 27 00:08:00 1992
  201.  
  202.   Lo Function: _RunExitList
  203.   Hi Function: UNKNOWN
  204.  
  205.  
  206.         If the exception handler signals that the exception is terminal, then 
  207.         the process is given a process termination exception. A similar dump
  208.         to the one above will then be given for the process termination.
  209.  
  210. EIP: 1a02c0a0, DLL: C:\OS2\DLL\DOSCALL1.DLL Func: DOSREAD
  211. Execption type 1 at 1a0502f1
  212.   Except #: c0010001  Process terminate
  213.   Flags:    00000001
  214.   Next Rec: c0000005
  215.   Except Addr: 1a0502f1
  216.   Num Parms: 0
  217. Exception in thread: 1
  218.  
  219. Pid: 000000f0  Tid:    00000001
  220. Cmd:        0  Value:  00716668
  221. Addr: 00022570  Buffer: 00037fd4
  222. Len:  00000024  Index:  00000000
  223. MTE:  0000030c
  224. EAX: 36000017  EBX: 00022970  ECX: 0002294c  EDX: 00000007
  225. ESP: 0002255c  EBP: 000226d4  ESI: 00000004  EDI: 00000004
  226. EIP: 0000c0a0  EFLAGS: 00002206
  227.   Carry Parity Aux Zero Sign Trap IntE Dir OFlow IOPL Nested Resume
  228.   NC    PE      0  NE    0    0    1   DN  NO    2    0      0
  229. CSLim 1c000000  CSBase: 00000000  CSAcc: df  CSAttr: d0  CS:005b
  230. DSLim 1c000000  DSBase: 00000000  DSAcc: f3  DSAttr: d0  DS:0053
  231. ESLim 1c000000  ESBase: 00000000  ESAcc: f3  ESAttr: d0  ES:0053
  232. FSLim 00000031  FSBase: 00050030  FSAcc: f3  FSAttr: 00  FS:150b
  233. GSLim 00000000  GSBase: 00000000  GSAcc: 00  GSAttr: 00  GS:0000
  234. SSLim 1c000000  SSBase: 00000000  SSAcc: f3  SSAttr: d0  SS:0053
  235. EBP:    000226d4        EIP:      1a02c0a0
  236.   Base: 1a020000        Rel:   0000c0a0        Len:    00010000
  237.   Object: 00000002
  238.   Module:   C:\OS2\DLL\DOSCALL1.DLL
  239.   Size:     87884
  240.   Timestamp:Mon Nov 23 08:01:48 1992
  241.  
  242.   Lo Function: DOSREAD
  243.   Hi Function: DOSCOPY
  244.  
  245. EBP:    000226e4        EIP:    00012a75
  246.   Base: 00010000        Rel:    00002a75  Len:    00010000
  247.   Object: 00000001
  248.   Module:   C:\WORK\DEBUG\CATCH.EXE
  249.   Size:     18778
  250.   Timestamp:Sun Sep 27 00:08:00 1992
  251.  
  252.   Lo Function: terminate
  253.   Hi Function: UNKNOWN
  254.  
  255. EBP:    00022754        EIP:    00011ea5
  256.   Base: 00010000        Rel:    00001ea5  Len:    00010000
  257.   Object: 00000001
  258.   Module:   C:\WORK\DEBUG\CATCH.EXE
  259.   Size:     18778
  260.   Timestamp:Sun Sep 27 00:08:00 1992
  261.  
  262.   Lo Function: mig_eib_store
  263.   Hi Function: UNKNOWN
  264.  
  265. EBP:    00022778        EIP:    000119f4
  266.   Base: 00010000        Rel:    000019f4        Len:    00010000
  267.   Object: 00000001
  268.   Module:   C:\WORK\DEBUG\CATCH.EXE
  269.   Size:     18778
  270.   Timestamp:Sun Sep 27 00:08:00 1992
  271.  
  272.   Lo Function: mig_eib_store
  273.   Hi Function: UNKNOWN
  274.  
  275. EBP:    000227b4        EIP:    00012144
  276.   Base: 00010000        Rel:    00002144        Len:    00010000
  277.   Object: 00000001
  278.   Module:   C:\WORK\DEBUG\CATCH.EXE
  279.   Size:     18778
  280.   Timestamp:Sun Sep 27 00:08:00 1992
  281.  
  282.   Lo Function: mig_eib_store
  283.   Hi Function: UNKNOWN
  284.  
  285. EBP:    00022b50        EIP:    1a02c60f
  286.   Base: 1a020000        Rel:    0000c60f        Len:    00010000
  287.   Object: 00000002
  288.   Module:   C:\OS2\DLL\DOSCALL1.DLL
  289.   Size:     87884
  290.   Timestamp:Mon Nov 23 08:01:48 1992
  291.  
  292.   Lo Function: DOSREAD
  293.   Hi Function: DOSCOPY
  294.  
  295. EBP:    ffffffff        EIP:    0001235c
  296.   Base: 00010000        Rel:    0000235c        Len:    00010000
  297.   Object: 00000001
  298.   Module:   C:\WORK\DEBUG\CATCH.EXE
  299.   Size:     18778
  300.   Timestamp:Sun Sep 27 00:08:00 1992
  301.  
  302.   Lo Function: mig_eib_store
  303.   Hi Function: UNKNOWN
  304.  
  305. EIP: 1a02c0a0, DLL: C:\OS2\DLL\DOSCALL1.DLL Func: DOSREAD
  306. Thread 1 Terminated
  307. EIP: 1a02c5ad, DLL: C:\OS2\DLL\DOSCALL1.DLL Func: DOSREAD
  308. Process Terminated
  309. EIP: 0001051c, DLL: C:\WORK\DEBUG\CATCH.EXE Func: _RunExitList
  310.  
  311.  
  312. Current Limitations
  313.  
  314. The current release has the current limitations:
  315.  
  316. 1)      Only the program started will be monitored.  Any subprocesses started by
  317.         the program will not be monitored.
  318.  
  319. 2)      The shareware version does not have the debugging DLLs.
  320.  
  321. 3)      The first release has an annoying flashing effect.  I am still working 
  322.         to find why this is happening.  Hopefully the next version will have
  323.         this fixed.
  324.  
  325. 4)      Crossing 16-32 bit function calls is not currently supported for the 
  326.         stack trace.
  327.  
  328. 5)      Tracing of 16 bit stacks may be incorrect for code with near calls in
  329.         the trace.
  330.  
  331.  
  332. Copyright and Legal Information
  333.  
  334. Sherlock is Copyrighted (c) 1992 by Harfmann Software.  All rights reserved.
  335.  
  336. Sherlock is not public domain or free software.
  337.  
  338. Sherlock is distributed under the Shareware concept. Non-registered users of
  339. Sherlock are granted a limited license to use Sherlock for a trial period of
  340. 2 weeks  in order to determine whether Sherlock suits their needs. Under no
  341. circumstances can an un-registered version of Sherlock be used by a business,
  342. organization, or institution of any kind after the trial period.
  343.  
  344. All users are granted a limited license to distribute shareware versions of
  345. Sherlock subject to the following restrictions:
  346.  
  347. - Sherlock is distributed in unmodified form, along with all program,
  348.   documentation, and any other files present in the original package.
  349. - Sherlock is not bundled with any other product.
  350. - No distribution fee is charged other than cost of materials.
  351.  
  352. Registered copies are NEITHER free software nor shareware. Users are granted
  353. unlimited use of registered copies of Sherlock subject to the following
  354. restrictions:
  355.  
  356. - Sherlock once registered may be installed and used on only one machine at a 
  357.   time.
  358.  
  359. - Users are not free to copy, modify, or redistribute registered copies of
  360.   Sherlock IN ANY WAY whatsoever.
  361.  
  362. Bulletin Board Services are free to post Sherlock for downloading to
  363. prospective users, providing that no fee is charged for such downloading,
  364. aside from possible connect charges.
  365.  
  366. Any other groups, companies, or organizations who wish to distribute Sherlock
  367. must obtain prior written approval from Harfmann Software.
  368.  
  369. There is no warranty for the program, to the extent permitted by applicable
  370. law.  This program is provided "as is" without warranty of any kind, either
  371. expressed or implied, including, but not limited to, theimplied warranties
  372. of merchantability and fitness for a particular purpose.  The entire risk
  373. as to the quality and performance of the program is with you.  Should the
  374. program prove defective, you assume the cost of all necessary servicing,
  375. repair or correction.
  376.  
  377. In no event unless required by applicable law or agreed to in writing
  378. will any copyright holder, or any other party who may modify and/or
  379. redistribute the program as permitted above, be liable to you for damages,
  380. including any general, special, incidental or consequential damages arising
  381. out of the use or inability to use the program (including but not limited
  382. to loss of data or data being rendered inaccurate or losses sustained by
  383. you or third parties or a failure of the program to operate with any other
  384. programs), even if such holder or other party has been advised of the 
  385. possibility of such damages.
  386.  
  387.  
  388. Registration and Ordering Information
  389.  
  390. Registering Sherlock will entitle you to continued use of Sherlock beyond the
  391. trial period. Furthermore, it will entitle you to receive, free of charge, the
  392. latest upgrade to Sherlock. You will also receive a set of DLLs to support
  393. debugging information.
  394.  
  395. To register your copy of Sherlock, fill out the order form on the following 
  396. page, and send it, along with a check or money order for $25 in U.S. funds to:
  397.  
  398. Harfmann Software
  399. 607 South 19th
  400. Lafayette, IN 47905
  401.  
  402. Corporate users and other institutions should inquire at the above address
  403. regarding charges for site licensing of Sherlock.
  404.  
  405. Note that continued use of an unregistered copy is a violation of the
  406. licensing agreement. Support Shareware-register your copy today!
  407.  
  408.  
  409.  
  410. Sherlock
  411.  
  412.  
  413.  
  414.                                      Order Form
  415.  
  416.  
  417.   Sherlock version 1.00
  418.   ------------------------------------------------------------
  419.  
  420.   Sherlock 1.00 (includes program disk & registration)
  421.  
  422.                   ____ @ $25 U.S. ______
  423.  
  424.   Please make checks or money orders payable in U.S. funds
  425.  
  426.  
  427.   Name      ________________________________________________
  428.  
  429.   Company   ________________________________________________
  430.  
  431.   Address   ________________________________________________
  432.  
  433.         ____________________________________________________
  434.  
  435.         ____________________________________________________
  436.  
  437.   Phone ____________________ Business ______________________
  438.  
  439.  
  440.   Where did you obtain Sherlock?
  441.  
  442.        _____________________________________________________
  443.  
  444.   Comments/Suggestion?
  445.  
  446.        _____________________________________________________
  447.  
  448.        _____________________________________________________
  449.  
  450.        _____________________________________________________
  451.  
  452.        _____________________________________________________
  453.