Provided by: libfam-dev_2.7.0-17.3_amd64 bug

NAME

       fam - File Alteration Monitor (FAM) library routines

SYNOPSIS

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

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.

       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.

USAGE

       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 procedures.

       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.

DATA STRUCTURES

       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 FAMSuspendMonitor.

       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:

       FAMChanged
                Some value which can be obtained with fstat 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  generated  when  monitoring  starts  on  a  nonexistent  file or
                directory.

       FAMStartExecuting
                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.

       FAMStopExecuting
                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.

       FAMCreated
                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.

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

       FAMExists
                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.

       FAMEndExist
                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 message.

       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 "/tmp/xyzzy".

PROCEDURES

       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 otherwise.

       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 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 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 otherwise.

       Because  famd  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  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.

SEE ALSO

       famd(8), fstat(2), poll(2), select(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 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.