FAM(3X) 																   FAM(3X)

NAME

       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;

       extern char *FamErrlist[];

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 communi-
       cate with the application.  The fam process is started when the first connection from any application to it is opened.  It exits after  all
       connections 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 structure 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, respectively.

       3.     Select on the fam socket file descriptor and call FAMPending when the fam socket is active, and FAMNextEvent when  FAMPending  indi-
	      cates  that  an event is available.  Alternatively, call FAMPending (or FAMNextEvent) periodically to check the socket connection to
	      fam 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 tempo-
	      rarily  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 fam.

DATA STRUCTURES

       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 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(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 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, fam generates a FAMAcknowledge event.  Also, if an invalid  pathname	is  specified,	fam   generates  a
		FAMAcknowledge event.

       FAMExists
		When the application requests a file be monitored, 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 generated as described above.   After
		the last FAMExists message, fam 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
       fam.  If an event applies to an entry in a monitored directory, the filename field contains the relative path only.  For  example,  if  the
       directory  /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 other-
       wise.

       FAMMonitorDirectory, FAMMonitorFile

       FAMMonitorDirectory and FAMMonitorFile tell FAM 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 informa-
       tion about files, when it is iconified, for example.  FAMResumeMonitor signals fam  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 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 directory, it should call FAMCancelMonitor.  This routine will signal fam not to moni-
       tor this directory anymore.  The FAMRequest structure is returned from the FAMMonitorFile or FAMMonitorDirectory routines.   FAMCancelMoni-
       tor 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 rou-
       tine 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 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  deter-
       mine 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.

							       Specialized Libraries								0a