Man Linux: Main Page and Category List


       fam - File Alteration Monitor (FAM) library routines


       #include <fam.h>

       extern int FAMOpen(FAMConnection* fc);

       extern int FAMOpen2(FAMConnection* fc,
                           const char* appName);

       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[];


       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.

       FAM  comes in two parts: famd, 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 libfam.a, which is loaded if the option
       -lfam is used with cc or ld.

       An application calls routines described here to  establish  a  list  of
       files  for  famdto  monitor.   famdgenerates  events  on  a  socket  to
       communicate with the application.  The famd process is started when the
       first  connection from any application to it is opened.  It exits after
       all connections to it have been closed.


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

       1.     Create a connection to famd by calling  FAMOpen.   This  routine
              will  pass  back  a  FAMConnection  structure  used  in  all FAM

       2.     Tell famd which files and  directories  to  monitor  by  calling
              FAMMonitorFile  and  FAMMonitorDirectory  to express interest in
              files and directories, respectively.

       3.     Select on the famd socket file descriptor  and  call  FAMPending
              when the famd socket is active, and FAMNextEvent when FAMPending
              indicates that  an  event  is  available.   Alternatively,  call
              FAMPending  (or  FAMNextEvent)  periodically to check the socket
              connection to famd to see if 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 or  directory,
              it  should  call  FAMCancelMonitor.  If the application wants to
              temporarily suspend monitoring of a file 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 the connection to famd.


       The FAMConnection Structure

       The FAMConnection data structure is created when opening  a  connection
       to  famd.   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  famd  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   FAMCancelMonitor  or  suspended,  using

       The FAMEvent Structure

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

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

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

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

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

                A file was created in a directory being monitored.  Note: this
                event is only  generated  for  files  created  directly  in  a
                directory    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.

                After  a  FAMCancelMonitor,  famd  generates  a FAMAcknowledge
                event.  Also,  if  an  invalid  pathname  is  specified,  famd
                generates a FAMAcknowledge event.

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

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

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


       FAMOpen, FAMClose

       The application opens a connection to famd by calling FAMOpen.  FAMOpen
       initializes the FAMConnection structure passed in to it and  returns  0
       if  successful, otherwise -1.  The parameter appName of FAMOpen2 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 famd connection.   It  returns  0  if  successful  and  -1

       FAMMonitorDirectory, FAMMonitorFile

       FAMMonitorDirectory  and FAMMonitorFile tell famd to start monitoring a
       directory or file, respectively.  The parameters to this function are a
       FAMConnection  (initialized  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 generated.  The application  can
       retrieve  this structure by calling FAMNextEvent (see description under

       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 famd to start monitoring 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 FAMRequest structure.
       The  FAMRequest  Structure  is  returned  from  the  FAMMonitorFile  or
       FAMMonitorDirectory  routines  and  return  0  if  successful  and   -1

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


       When  an  application  is  finished  monitoring a file or directory, it
       should call FAMCancelMonitor.  This routine will  signal  famd  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  until  a  FAM  event  is
       received.   If  blocking  is  not  desirable,  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 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 socket, and
       returns it to the application in the form of a FAMEvent.

       FAMNextEvent returns 1 if successful and -1 otherwise.


       famd(8), fstat(2), poll(2), select(2)


       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.

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

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