AMIGA - MEM_#?
 ----------------------------------------------------------------------------

   NAME

      mem_attachsniffer() - Installs a sniffer on a given msg.
                            port.



   SYNOPSIS

      ptr = mem_attachsniffer(mp, usercode, userdata);

      void *mem_attachsniffer(
                            struct MsgPort *, void *, void *);



   FUNCTION

      This function makes it possible to spy on msg. port I/O
      of virtually any task that is running in the system.



   INPUTS

      mp       - PA_SIGNAL based message port that references
                 a task that is running. Orphaned/incompatible
                 msg. ports will be rejected!

      usercode - Sniffer function as created with magic macro
                 QDEV_MEM_SNIFFUNC().

      userdata - User supplied data. You can pass the 'mp' ptr
                 here to have quick access in sniffer func.



   RETURNS

      Function returns 'ient' handle if all went fine or NULL
      if 'mp' is invalid or there is not enough memory avail.



   BASES

      SysBase



   NOTES

      Yes, this code relies on private task exception mechanism
      so you must treat them pretty much like interrupts!

      Yes, it is possible to attach sniffer to message ports of
      different than your task.

      Yes, unlike 'mem_addexhandler()' which is restricted to
      only one handler per signal this routine allows multiple
      handlers on single mp/signal.

      No, it does not interfere with  'mem_addexhandler()'  and
      'mem_remexhandler()'. All will work as if there were no
      sniffers installed.

      Note that sniffers are always called in LIFO order. Every
      newly added sniffer is the first to call! As to exception
      routine, it will be called last. This allows to see what
      arrived on port before exception handler processes it.

      Remark! Sniffers (and especially long sniffer chains) are
      slower than exceptions alone!



   SEE ALSO

      mem_detachsniffer(), mem_addexhandler(),
      mem_remexhandler() 



   EXAMPLE

      ...

      #define ___QDEV_DEBUGINFO

      QDEV_MEM_SNIFFUNC
      (
        mysniffer,

        QDEV_MEM_SNIFEXEC();
        QDEV_MEM_SNIFUSER(struct MsgPort *, mp);
        struct Message *mn;

        QDEV_HLP_ITERATE(&mp->mp_MsgList, struct Message *, mn)
        {
          /*
           * This will be visible on remote terminal connected
           * via serial port or if redirector such as 'sashimi'
           * was started then in other shell.
          */
          QDEVDEBUG_N("mn_ReplyPort\nmn_Length\n\n\n",
                              mn->mn_ReplyPort, mn->mn_Length);
        }

        /*
         * Let the task, process what is in the queue. Without
         * this statement task may never notice that something
         * was sent to its message port.
        */
        QDEV_MEM_SNIFPASS();
      );

      ...

      void *spy;
      struct MsgPort *mp = <pointer>;

      if ((spy = mem_attachsniffer(mp, mysniffer, mp)))
      {
        ...
      }

      ...



   BUGS

      None known.



 ----------------------------------------------------------------------------