Seth Woolley's Man Viewer

Manual for fam - man 3 fam

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

FAM(3)                                SGI                               FAM(3)



NAME
       fam(1m,3) - 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;

       extern char *FamErrlist[];


DESCRIPTION
       FAM,  the File Alteration Monitor, is a subsystem that applications can
       use to be notified when specific files or directories are changed.   It
       is intended as a replacement for mechanisms such as poll and select(2,7,2 select_tut).

       FAM  comes in(1,8) two parts: famd(5,8), the daemon that listens for requests and
       provides notifications, and libfam a library that  client  applications
       can use to communicate with FAM.

       libfam's  routines are found in(1,8) libfam.a, which is loaded if(3,n) the option
       -lfam is used with cc or ld(1,8).

       An application calls routines described here to  establish  a  list  of
       files for famd(5,8)to monitor.  famd(5,8)generates events on a socket(2,7,n) to communi-
       cate with the application.  The famd(5,8) process is started when the  first
       connection  from  any  application to it is opened.  It exits after all
       connections to it have been closed.


USAGE
       Here are the steps required to use FAM in(1,8) an application:


       1.     Create a connection to famd(5,8) by calling  FAMOpen.   This  routine
              will  pass back a FAMConnection structure used in(1,8) all FAM proce-
              dures.

       2.     Tell famd(5,8) which files and directories to monitor by calling FAM-
              MonitorFile and FAMMonitorDirectory to express interest in(1,8) files
              and directories, respectively.

       3.     Select on the famd(5,8) socket(2,7,n) file(1,n) descriptor  and  call  FAMPending
              when the famd(5,8) socket(2,7,n) is active, and FAMNextEvent when FAMPending
              indicates that an event is available.  Alternatively, call FAMP-
              ending  (or  FAMNextEvent) periodically to check the socket(2,7,n) con-
              nection to famd(5,8) to see if(3,n) any new information has  arrived.   If
              there  are no events pending, FAMNextEvent blocks until an event
              occurs.

       4.     When the application is through monitoring a file(1,n) or  directory,
              it  should  call  FAMCancelMonitor.  If the application wants to
              temporarily suspend monitoring of a file(1,n) or  directory,  it  may
              call  FAMSuspendMonitor.  When the application is ready to start
              monitoring again, it calls FAMResumeMonitor.

       5.     Before the application exits, it should call  FAMClose  to  free
              resources  associated  with  files  still being monitored and to
              close(2,7,n) the connection to famd(5,8).


DATA STRUCTURES
       The FAMConnection Structure

       The FAMConnection data structure is created when opening  a  connection
       to  famd(5,8).   Subsequently  it  is  passed into all FAM procedures.  This
       structure has all the information in(1,8) it to communicate to fam(1m,3).

       Use the macro FAMCONNECTION_GETFD to access(2,5) the file(1,n) descriptor  inside
       the FAMConnection, rather than accessing it directly.

       The FAMRequest Structure

       When  famd(5,8)  is called on to monitor a file(1,n), it passes back a FAMRequest
       structure.  This structure uniquely identifies the request so  that  it
       may  be  cancelled,  using FAMCancelMonitor or suspended, using FAMSus-
       pendMonitor.

       The FAMEvent Structure

       Changes to files and directories are encoded in(1,8) the FAMEvent structure.
       The code field of this structure contains one of the following enumera-
       tion constants:

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

       FAMDeleted
                A  file(1,n)  or  directory being monitored was deleted or its name
                was changed.  This event is  also  generated  when  monitoring
                starts on a nonexistent file(1,n) or directory.

       FAMStartExecuting
                An  executable  file(1,n) or shared library being monitored started
                executing.  If multiple processes execute the same file(1,n),  this
                event only occurs when the first process starts.

       FAMStopExecuting
                An executable file(1,n) being monitored which was running finished.
                If multiple processes from an  executable  are  running,  this
                event is only generated when the last one finishes.

       FAMCreated
                A file(1,n) was created in(1,8) a directory being monitored.  Note: this
                event is only generated for files created directly in(1,8) a direc-
                tory  being  monitored;  subdirectories  are not automatically
                monitored.

       FAMMoved FAMMoved events never occur.  The name remains defined so that
                programs that reference it will still compile.

       FAMAcknowledge
                After  a  FAMCancelMonitor,  famd(5,8)  generates  a FAMAcknowledge
                event.  Also, if(3,n) an invalid pathname is specified, famd(5,8) gener-
                ates a FAMAcknowledge event.

       FAMExists
                When the application requests a file(1,n) be monitored, famd(5,8) gener-
                ates a FAMExists event for that file.   When  the  application
                requests  a directory be monitored, famd(5,8) generates a FAMExists
                event for that directory and every file(1,n) directly contained  in(1,8)
                that directory.

       FAMEndExist
                When the application requests a file(1,n) directory be monitored, a
                series of FAMExists events is generated  as  described  above.
                After the last FAMExists message, famd(5,8) generates a FAMEndExist
                message.

       If a FAM event applies to a file(1,n)  or  directory  being  monitored,  the
       FAMEvent's filename field contains the full pathname that was passed to
       famd(5,8).  If an event applies to an entry in(1,8) a  monitored  directory,  the
       filename  field  contains  the relative path only.  For example, if(3,n) the
       directory /tmp/xyzzy were monitored, and the file(1,n) /tmp/xyzzy/plugh were
       deleted,  a  FAMDeleted  event would be generated containing "plugh" in(1,8)
       filename.  If the directory itself were deleted, filename would contain
       "/tmp/xyzzy".

PROCEDURES
       FAMOpen, FAMClose

       The application opens a connection to famd(5,8) by calling FAMOpen.  FAMOpen
       initializes the FAMConnection structure passed in(1,8) to it and  returns  0
       if(3,n)  successful, otherwise -1.  The variable char* appName should be set(7,n,1 builtins)
       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 famd(5,8) connection.  It returns 0 if(3,n) successful and -1 other-
       wise.

       FAMMonitorDirectory, FAMMonitorFile

       FAMMonitorDirectory  and FAMMonitorFile tell famd(5,8) to start monitoring a
       directory or file(1,n), respectively.  The parameters to this function are a
       FAMConnection (initialized by FAMOpen), a FAMRequest structure, a file-
       name and a user data pointer.  The FAMRequest structure is modified  to
       subsequently  identify  this  request.   When  the  file(1,n)  or  directory
       changes, a FAM event structure will be generated.  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(1,n) itself); FAMMonitorFile
       monitors only what happens to a particular file.  Both routines  return
       0 if(3,n) successful and -1 otherwise.

       The filename argument must be a full pathname.

       FAMSuspendMonitor, FAMResumeMonitor

       FAMSuspendMonitor  temporarily suspends monitoring of files or directo-
       ries.  This is useful when an application is not displaying information
       about  files, when it is iconified, for example.  FAMResumeMonitor sig-
       nals famd(5,8) to start monitoring the file(1,n)  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 FAMRequest structure.
       The FAMRequest Structure is returned from the FAMMonitorFile or FAMMon-
       itorDirectory routines and return 0 if(3,n) successful and -1 otherwise.

       Because famd(5,8) runs as an asynchronous process, FAMNextEvent may return a
       few  events  regarding a given request after that request has been sus-
       pended.

       FAMCancelMonitor

       When an application is finished monitoring  a  file(1,n)  or  directory,  it
       should  call  FAMCancelMonitor.   This  routine will signal(2,7) famd(5,8) not to
       monitor this directory anymore.  The FAMRequest structure  is  returned
       from  the  FAMMonitorFile  or FAMMonitorDirectory routines.  FAMCancel-
       Monitor returns 0 if(3,n) successful and -1 otherwise.


       FAMPending, FAMNextEvent

       FAMPending returns 1 if(3,n) an event is waiting and 0 if(3,n) no event is  wait-
       ing.  It also returns 1 if(3,n) an error(8,n) 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  until a FAM event is
       received.  If blocking is not desirable, call FAMPending before FAMNex-
       tEvent,  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(1,n)
           descriptor returned from FAMOpen, in(1,8) the FAMConnection structure.
           When this file(1,n) descriptor becomes active, the application 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 FAMNextEvent to
           retrieve the pending FAM event.

       FAMNextEvent reads any information that is  on  the  famd(5,8)  socket(2,7,n),  and
       returns it to the application in(1,8) the form of a FAMEvent.

       FAMNextEvent returns 1 if(3,n) successful and -1 otherwise.



SEE ALSO
       famd(5,8)(8), fstat(1), poll(2), select(2,7,2 select_tut)(2)


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(1,n) or directory to which those events refer.

       FAMErrno and FamErrlist are not set(7,n,1 builtins) when errors occur.

       When  a  shell  script  is run, notification is generated for the shell
       executing the script.

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

       When using the Linux DNotify kernel monitor,  a  file(1,n)  handle  will  be
       opened  for each file(1,n) famd(5,8) is asked to monitor, meaning the file(1,n) system
       the file(1,n) resides on can not be unmounted.



fam(1m,3) (fam(1m,3) 2.6.10)               January 19, 2003                         FAM(3)

References for this manual (incoming links)