IMON(7M)                                                              IMON(7M)


NAME
     imon - inode monitor device

SYNOPSIS
     #include <sys/imon.h>
     /dev/imon

DESCRIPTION
     The inode monitor driver is a pseudo device driver which enables a user
     level program to monitor filesystem activity on a file by file basis.
     The application program expresses interest in specific files by means of
     an ioctl request that specifies the pathname of the file and an
     indication of what types of events are to be monitored.  As various
     actions take place on a file in which interest has been expressed, imon
     posts events through a queue that may be read via the read system call.

   Events
     Calls to read return an integral number of imon queue elements.  Each
     queue element has the structure given below.

     typedef struct {
          ino_t          qe_inode;  /* inode number of file  */
          dev_t          qe_dev;         /* device of file  */
          intmask_t qe_what;   /* what events occurred  */
          } qelem_t;

     The qe_inode is a key that uniquely describes every file within a
     filesystem and matches the st_ino field of the file's stat structure (see
     stat(4) ).  The qe_dev field similarly matches the st_dev field of the
     file's stat structure.  These two fields together uniquely describe a
     file in the system.  The third field, qe_what, contains a bit-mask
     describing what event or events took place on that file.  The possible
     events are:

     IMON_CONTENT   The contents or size of the file have changed.  This is
                    typically caused by a write(2) call made by some process.

     IMON_ATTRIBUTE The mode or ownership have changed on the file.  This is
                    typically caused by a chown(2) or chmod(2) system call.

     IMON_DELETE    The last link to the file has gone away.  When this event
                    is sent, all interest in the file is implicitly revoked.
                    Note that if a process has the file open when it is
                    removed from the directory structure, this event will not
                    be generated until the file is closed.

     IMON_EXEC      The file represents an executable command and a process
                    has started executing that command.  If multiple instances
                    of the same command are subsequently started, an event is
                    not generated.  Therefore, the IMON_EXEC event only means
                    that at least one process is executing from that file.
                    When an interpreted executable (seeexecve(2)) is executed,


                    then IMON_EXEC events are generated both for the
                    interpreted script and for the interpreter.

     IMON_EXIT      The last process executing the file has exited.

     IMON_OVER      The imon event queue has overflowed.  When this occurs,
                    the client process must re-express interest in each file
                    to determine its true state.

   Controls
     The following structure is used by the IMONIOC_EXPRESS and IMONIOC_REVOKE
     controls described below.

     typedef struct {
          char *         in_fname;  /* pathname */
          struct stat *  in_sb;          /* optional status return buffer */
          intmask_t in_what;   /* what types of events to send  */
          } interest_t;

     IMONIOC_EXPRESS
                    Express interest in the file whose name is given in
                    in_fname.  If in_fname represents a symbolic link, the
                    action takes place on the link itself, not the file to
                    which it points.  Only events in the bit-mask in_what will
                    be generated.  The in_sb field optionally points to a
                    stat(4) buffer that will be filled in with the current
                    state of the file.  This allows the imon client to
                    atomicly express interest and get the current state of a
                    file.  Multiple calls may be made on the same file and
                    have a cumulative effect.

     IMONIOC_REVOKE Revoke interest in the file whose name is given by
                    in_fname.  The in_what field is used to determine which
                    interests will be revoked.  As with IMONIOC_EXPRESS,
                    multiple calls may be made on the same file and have a
                    cumulative effect.

     IMONIOC_QTEST  Returns the number of events waiting to be read in the
                    event queue.

BUGS
     Files in an NFS mounted filesystem will only generate events for things
     that happen as a result of local activity; changes made remotely on the
     NFS server will not be seen through imon.

CAVEATS
     The imon driver is intended to be used only by the file access monitoring
     daemon (fam) and the interface is likely to change in future releases.
     Client programs should communicate with fam for monitoring services, not
     with imon directly.


                                                                        Page 2