home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / debug / Snooper / FSG / FSG.doc < prev    next >
Text File  |  1995-06-25  |  7KB  |  209 lines
  1.  
  2.            The File System Guardian -- Yet Another Dos Snoop Utility
  3.  
  4.                  (c) 1994 Martin Mares, MJSoft System Software
  5.  
  6. ================================================================================
  7.  
  8.  
  9. Preface
  10. =======
  11.  
  12.    FSG,  its  documentation  and  the ss.library are Copyright (c) Martin Mares,
  13. MJSoft System Software, Prague, Czech Republic.
  14.  
  15.    This  archive  can  be  freely redistributed, as long as all of its files are
  16. included   in   their   original   form  without  any  additions,  deletions  or
  17. modifications,  and  no more than a nominal fee is charged for its distribution.
  18. All  copyright notices in the programs and accompanying documentation files must
  19. remain  on  their  places.  Also '.displayme' and other similar files may not be
  20. added.  This is generally known as FREEWARE.
  21.  
  22.    This  software  is  provided  "AS  IS"  without  warranty of any kind, either
  23. expressed  or  implied.   The author is not responsible for any damage caused by
  24. it.
  25.  
  26.  
  27. Introduction
  28. ============
  29.  
  30.    There  exist  people  which  need to monitor disk / file activity.  And there
  31. also exist AmigaDOS / disk / file activity monitors.  Oh yes, they are not quite
  32. the  same,  there  are many differences between them...  and FSG tries to be the
  33. best of them.
  34.  
  35.    A  long  time  ago,  there were some ancient operating systems called 1.3 and
  36. there  also  were numerous tools for monitoring file access under them.  But all
  37. of  them  used a very stupid method -- they simply patched all dos.library calls
  38. and watched who and when is calling them.  The authors probably didn't know that
  39. calling dos.library is one, but not the only one method of accessing files.  You
  40. can:
  41.  
  42.    (1)  Call dos -- the most usual case.
  43.  
  44.    (2)  Call BCPL functions through the Global Vector. Most 1.3 commands do
  45. this.
  46.  
  47.    (3)  Use asynronous I/O with your own packet sending mechanism.
  48.  
  49.    It's  the  reason  why  most  DOS snoppers don't catch all the accesses.  And
  50. (what  is  even worse) they are usually designed for being used by unexperienced
  51. users thus they don't show detailed information about what is going on.
  52.  
  53.    FSG tries to be better.
  54.  
  55.  
  56. Requirements
  57. ============
  58.  
  59.    - Kickstart 2.04 or higher.
  60.  
  61.    - The ss.library version 5.0 or newer (included in this archive)
  62.  
  63.  
  64. Usage
  65. =====
  66.  
  67.    FSG must be started from the shell.
  68.  
  69.    Usage:
  70.  
  71.       FSG <devices> [NORES] [MIN] [RESOLVE]
  72.  
  73. <devices> - list of DOS devices you want to look at.  Usually all hard drives,
  74.         floppy drives and the RAM disk.
  75.  
  76.     NORES - disable waiting for packet results. In all normal cases, all packets
  77.         are reported as soon as the result code is returned back to the
  78.         caller. In some cases, you need to report the packets immediately
  79.         (for example when debugging a file system) and you can force it by
  80.         this option.
  81.  
  82.       MIN - show only important events - opening of files, locking of
  83.         directories etc. If you are not an experienced user, turn it on to
  84.         hide a lot of confusing output.
  85.  
  86.   RESOLVE - show full names instead of file handles and locks. This slightly
  87.         slows down system operation, but displays a more useful output.
  88.         (no one usually knows what does a file handle 0x221234 mean).
  89.  
  90.    After invocation, FSG starts looking for packets and displaying all caught
  91. events. It can be stopped by CTRL-C (or by sending a BREAK to it). If stopped,
  92. you must wait a moment while the buffers are deallocated and unread messages
  93. thrown away.
  94.  
  95.    Only one FSG may be active at given time.
  96.  
  97.  
  98. Output
  99. ======
  100.  
  101.    The output consists has the following format:
  102.  
  103. <device> <task> <action> <parameters> -> <result> <ioerr>
  104.  
  105.      <device> - the device handler or filesystem this packet is sent to. It's the
  106.         name of the handler task that needn't to be the same as the
  107.         device name given.
  108.  
  109.        <task> - task requesting the operation. If it's a CLI process running a
  110.         command, the command name is displayed instead.
  111.  
  112.      <action> - packet type (see the table below)
  113.  
  114.  <parameters> - packet parameters - displayed as hexadecimal numbers or strings.
  115.  
  116.      <result> - primary result of the packet. Zero or FFFFFFFF used to signalize
  117.         failure. In this case, <ioerr> contains detailed description of
  118.         the error.
  119.  
  120.       <ioerr> - I/O Error code. If it's some standard code, its name is shown
  121.         instead. If no error occured, this needn't to be zero (but
  122.         usually is).
  123.  
  124.  
  125. Known packets
  126. =============
  127.  
  128.    - This table is not complete. If you know anything better than me, let me
  129. know.
  130.  
  131. NIL                            -
  132. GET_BLOCK    ?????                    ?
  133. TIMER                            bool
  134. SET_MAP        ?????                    ?
  135. DISK_TYPE    ?????                    ?
  136. DISK_CHANGE                        bool
  137. READ_RETURN                        ??? (does return?)
  138. WRITE_RETURN                        ??? (does return?)
  139. EVENT        ?????                    ?
  140. WRITE_PROTECT    flag    passkey                bool
  141. STARTUP        ?    startup    devnode            bool
  142. DIE                            bool
  143. FINDINPUT    fh    lock    name            bool
  144. FINDOUTPUT    fh    lock    name            bool
  145. FINDUPDATE    fh    lock    name            bool
  146. READ        arg1    &buf    len            len
  147. WRITE        arg1    &buf    len            len
  148. END        arg1                    bool
  149. SEEK        arg1    pos    mode            oldpos
  150. SET_FILE_SIZE    arg1    pos    mode            oldpos
  151. EXAMINE_NEXT    lock    fib                bool
  152. EXAMINE_OBJECT    lock    fib                bool
  153. INFO        lock    info                bool
  154. DISK_INFO    info                    bool
  155. PARENT        lock                    lock
  156. DELETE_OBJECT    lock    name                bool
  157. CREATE_DIR    lock    name                lock
  158. LOCATE_OBJECT    lock    name    mode            lock
  159. COPY_DIR    lock                    lock
  160. FREE_LOCK    lock                    bool
  161. SET_PROTECT    -    lock    name    mask        bool
  162. SET_COMMENT    -    lock    name    comment        bool
  163. RENAME_OBJECT    slock    sname    dlock    dname        bool
  164. RENAME_DISK    name                    bool
  165. MORECACHE    num                    bool
  166. WAITCHAR    ticks                    bool
  167. FLUSH                            bool
  168. SCRMODE        bool                    bool
  169. CURRENT_VOLUME    [arg1]                    volume
  170. SET_DATE    -    lock    name    stamp        bool
  171. SET_OWNER    -    -    lock    userinfo    bool
  172. INHIBIT        bool                    bool
  173. SAME_LOCK    lock    lock                bool
  174. CHANGE_SIGNAL    arg1    task    0            bool
  175. FORMAT        volname    dostype                bool
  176. MAKE_LINK    lock    name    dest!#    soft        bool
  177. READ_LINK    lock    name!C    buf    size        len
  178. FH_FROM_LOCK    fh    lock                bool
  179. IS_FILESYSTEM                        bool
  180. CHANGE_MODE    type    lk/fh    newmode            bool
  181. COPY_DIR_FH    arg1                    lock
  182. PARENT_FH    arg1                    lock
  183. EXAMINE_ALL    lock    buffer    size    data    ctrl    bool
  184. EXAMINE_ALL_END    lock    buffer    size    data    ctrl    bool
  185. EXAMINE_FH    arg1    fib                bool
  186. LOCK_RECORD    arg1    offset    length    mode    timout    bool
  187. FREE_RECORD    arg1    offset    length            bool
  188. START_NOTIFY    notreq                    bool
  189. REMOVE_NOTIFY    notreq                    bool
  190. SERIALIZE_DISK                        bool
  191.  
  192. !C = stored as C-string.
  193. !# = BPTR Lock if hard, C-string if soft.
  194. ???,????? = I know nothing about it.
  195. ? = Unknown parameter, always zero.
  196.  
  197.    For novices:
  198.  
  199. FINDINPUT    open existing file
  200. FINDOUTPUT    create new file
  201. FINDUPDATE    open existing file or create new one if it doesn't exist
  202. LOCATE_OBJECT    find and lock given object
  203.  
  204.  
  205. Notes
  206. =====
  207.  
  208.    Send suggestions, flames and bug reports to <mjsoft@k332.feld.cvut.cz>.
  209.