fam - File Alteration Monitor (FAM) library routines


SYNOPSIS

       #include <fam.h>

       extern int FAMOpen(FAMConnection* fc);

       extern int FAMClose(FAMConnection* fc);

       extern int FAMMonitorDirectory(FAMConnection *fc,
                                      char *filename,
                                      FAMRequest* fr,
                                      void* userData);

       extern int FAMMonitorFile(FAMConnection *fc,
                                 char *filename,
                                 FAMRequest* fr,
                                 void* userData);

       int FAMSuspendMonitor(FAMConnection *fc, FAMRequest *fr);

       int FAMResumeMonitor(FAMConnection *fc, FAMRequest *fr);

       int FAMCancelMonitor(FAMConnection *fc, FAMRequest *fr);

       int FAMNextEvent(FAMConnection *fc, FAMEvent *fe);

       int FAMPending(FAMConnection* fc);

       typedef struct {
           int fd;
       } FAMConnection;

       #define FAMCONNECTION_GETFD(fc)      (fc->fd)

       typedef struct {
           int reqnum;
       } FAMRequest;

       enum FAMCodes { FAMChanged=1, FAMDeleted=2, FAMStartExecuting=3,
           FAMStopExecuting=4, FAMCreated=5, FAMMoved=6, FAMAcknowledge=7,
           FAMExists=8, FAMEndExist=9 };

       typedef struct {
           FAMConnection* fc;
           FAMRequest fr;
           char hostname[MAXHOSTNAMELEN];
           char filename[NAME_MAX];
           void *userdata;
           FAMCodes code;
       } FAMEvent;

       extern int FAMErrno;



DESCRIPTION

       FAM  monitors  files and directories, notifying interested
       applications of changes.  Routines for communicating  with
       the  fam(1M)  server  process  are  found in ``libfam.a'',
       which is loaded if the option ``-lfam'' is used with cc(1)
       or  ld(1).   The library ``libC.a'' (``-lC'') must also be
       specified.

       An application calls routines described here to  establish
       a  list of files for fam to monitor.  Fam generates events
       on a socket to communicate with the application.  The  fam
       process  is  started  when  the  first connection from any
       application to it is opened.  It exits after  all  connec­
       tions to it have been closed.


USING FAM

       Here are the steps required to use FAM in an application:

       1.     Create  a  connection  to  fam  by calling FAMOpen.
              This routine will pass back a FAMConnection  struc­
              ture used in all fam procedures.

       2.     Tell  fam which files and directories to monitor by
              calling FAMMonitorFile and  FAMMonitorDirectory  to
              express  interest in files and directories, respec­
              tively.

       3.     Select on the fam socket file descriptor  and  call
              FAMPending  when the fam socket is active, and FAM­
              NextEvent when FAMPending indicates that  an  event
              is  available.   Alternatively, call FAMPending (or
              FAMNextEvent) periodically to check the socket con­
              nection  to  fam  to see if any new information has
              arrived.  If there are no events  pending,  FAMNex­
              tEvent blocks until an event occurs.

       4.     When  the  application is through monitoring a file
              or directory, it should call FAMCancelMonitor.   If
              the  application wants to temporarily suspend moni­
              toring of a file or directory, it may call  FAMSus­
              pendMonitor.   When  the  application  is  ready to
              start monitoring again, it calls  FAMResumeMonitor.

       5.     Before  the  application exits, it should call FAM­
              Close to free resources associated with files still
              being monitored and to close the connection to fam.

       The FAMConnection Structure

       The FAMConnection data structure is created when opening a
       connection to FAM.  Subsequently it is passed into all FAM
       procedures.  This structure has all the information in  it
       to communicate to fam.

       Use  the  macro  FAMCONNECTION_GETFD  to  access  the file
       descriptor inside the FAMConnection, rather than accessing
       it directly.

       The FAMRequest Structure

       When  fam is called on to monitor a file, it passes back a
       FAMRequest structure.  This structure uniquely  identifies
       the  request so that it may be cancelled, using FAMCancel­
       Monitor or suspended, using FAMSuspendMonitor.

       The FAMEvent Structure

       Changes to  files  and  directories  are  encoded  in  the
       FAMEvent structure.  The code field of this structure con­
       tains one of the following enumeration constants:

       FAMChanged
                Some value which can be  obtained  with  fstat(1)
                changed  for a file or directory being monitored.

       FAMDeleted
                A file or directory being monitored  was  deleted
                or its name was changed.  This event is also gen­
                erated when monitoring starts  on  a  nonexistent
                file or directory.

       FAMStartExecuting
                An  executable file or shared library being moni­
                tored started executing.  If  multiple  processes
                execute  the  same  file,  this event only occurs
                when the first process starts.

       FAMStopExecuting
                An executable file being monitored which was run­
                ning  finished.   If  multiple  processes from an
                executable are running, this event is only gener­
                ated when the last one finishes.

       FAMCreated
                A  file  was  created  in a directory being moni­
                tored.  Note: this event is  only  generated  for
                files created directly in a directory being moni­
                tored; subdirectories are not automatically moni­
                tored.

                defined so that programs that reference  it  will
                still compile.

       FAMAcknowledge
                After  a FAMCancelMonitor, fam generates a FAMAc­
                knowledge event.  Also, if an invalid pathname is
                specified, fam  generates a FAMAcknowledge event.

       FAMExists
                When the application requests  a  file  be  moni­
                tored,  fam  generates a FAMExists event for that
                file.  When the application requests a  directory
                be monitored, fam generates a FAMExists event for
                that directory and every file directly  contained
                in that directory.

       FAMEndExist
                When the application requests a file directory be
                monitored, a series of FAMExists events is gener­
                ated  as  described above.  After the last FAMEx­
                ists message, fam generates  a  FAMEndExist  mes­
                sage.

       If  a FAM event applies to a file or directory being moni­
       tored, the FAMEvent's filename  field  contains  the  full
       pathname  that  was passed to fam.  If an event applies to
       an entry in a monitored directory, the filename field con­
       tains  the relative path only.  For example, if the direc­
       tory  /usr/tmp/xyzzy  were   monitored,   and   the   file
       /usr/tmp/xyzzy/plugh   were  deleted,  a  FAMDeleted event
       would be generated containing "plugh" in filename.  If the
       directory  itself  were  deleted,  filename  would contain
       "/usr/tmp/xyzzy".


PROCEDURES

       FAMOpen, FAMClose

       The application opens  a  connection  to  fam  by  calling
       FAMOpen.   FAMOpen initializes the FAMConnection structure
       passed in to it and returns 0 if successful, otherwise -1.
       The  variable  char*  appName should be set to the name of
       your application. The FAMConnection structure is passed to
       all subsequent FAM procedure calls.

       FAMClose frees resources associated with files still being
       monitored and closes a fam connection.  It  returns  0  if
       successful and -1 otherwise.

       FAMMonitorDirectory, FAMMonitorFile

       FAMMonitorDirectory  and  FAMMonitorFile tell FAM to start
       monitoring  a  directory  or  file,   respectively.    The

       ized by FAMOpen), a FAMRequest structure, a filename and a
       user  data  pointer.  The FAMRequest structure is modified
       to subsequently identify this request.  When the  file  or
       directory  changes,  a  FAM event structure will be gener­
       ated.  The application  can  retrieve  this  structure  by
       calling FAMNextEvent (see description under FAMNextEvent).

       FAMMonitorDirectory monitors changes that happens  to  the
       contents  of  the directory (as well as the directory file
       itself); FAMMonitorFile monitors only what  happens  to  a
       particular file.  Both routines return 0 if successful and
       -1 otherwise.

       The filename argument must be a full pathname.

       FAMSuspendMonitor, FAMResumeMonitor

       FAMSuspendMonitor temporarily suspends monitoring of files
       or directories.  This is useful when an application is not
       displaying information about files, when it is  iconified,
       for  example.  FAMResumeMonitor signals fam to start moni­
       toring the file or directory again.  Changes  which  occur
       while  monitoring  is suspended are enqueued and delivered
       when monitoring is resumed.

       Both of these routines take a FAMConnection and  a  FAMRe­
       quest  structure.   The  FAMRequest  Structure is returned
       from the FAMMonitorFile  or  FAMMonitorDirectory  routines
       and return 0 if successful and -1 otherwise.

       Because  fam runs as an asynchronous process, FAMNextEvent
       may return a few events regarding a  given  request  after
       that request has been suspended.

       FAMCancelMonitor

       When an application is through monitoring a file or direc­
       tory, it should call FAMCancelMonitor.  This routine  will
       signal  fam  not  to  monitor this directory anymore.  The
       FAMRequest structure is returned from  the  FAMMonitorFile
       or FAMMonitorDirectory routines.  FAMCancelMonitor returns
       0 if successful and -1 otherwise.

       FAMPending, FAMNextEvent

       FAMPending returns 1 if an event is waiting and  0  if  no
       event  is waiting.  It also returns 1 if an error has been
       encountered.  This  routine  returns  immediately  to  the
       caller.

       FAMNextEvent will get the next FAM event.  If there are no
       FAM events waiting, then the  calling  application  blocks

       able, call FAMPending before FAMNextEvent, and  only  call
       FAMNextEvent when FAMPending says an event is available.

       There  are  two  ways  to  for applications to receive FAM
       events:

       1. The Select approach - The application  selects  on  the
       file
           descriptor returned from FAMOpen, in the FAMConnection
       structure.
           When this file descriptor becomes active, the applica­
       tion calls
           FAMPending  to  determine  whether a complete event is
       ready, and
           FAMNextEvent to retrieve the pending FAM event.

       2. The Polling approach - The application calls FAMPending
           periodically  (usually  when the system is waiting for
       input).
           When FAMPending returns 1, the application calls  FAM­
       NextEvent to
           retrieve the pending FAM  event.

       FAMNextEvent  reads  any  information  that  is on the fam
       socket, and returns it to the application in the form of a
       FAMEvent.

       FAMNextEvent returns 1 if successful and -1 otherwise.


SEE ALSO

       fam(1M).


BUGS

       The FAMMoved event is not currently supported.

       FAMNextEvent  may  not  initialize the FAMEvent's filename
       field for FAMEndExist and FAMAcknowledge events.  Use  the
       request number to determine the file or directory to which
       those events refer.

       FAMErrno and FamErrlist are not set when errors occur.

       When a shell script is run, notification is generated  for
       the shell executing the script, typically sh(1) or csh(1).

       Each process is limited to 1000 active requests at a time.


Man(1) output converted with man2html