Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for fam (redhat section 3X)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

FAM(3X) 										  FAM(3X)

       fam - File Alteration Monitor (FAM) library routines

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

       FAM  monitors  files  and directories, notifying interested applications of changes.  Rou-
       tines 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 moni-
       tor.   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 connections to it have been closed.

       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 FAM-
	      Connection structure used in all fam procedures.

       2.     Tell fam which files and directories to monitor by calling FAMMonitorFile and  FAM-
	      MonitorDirectory 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 indicates  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 FAM-
	      CancelMonitor.  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 fam.

       The FAMConnection Structure

       The  FAMConnection  data  structure  is	created when opening a connection to FAM.  Subse-
       quently 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 contains one of the following enumeration constants:

		Some  value  which  can be obtained with fstat(1) 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 direc-

		An executable file or shared library being monitored started executing.  If  mul-
		tiple  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  pro-
		cesses 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 gen-
		erated	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 ref-
		erence it will still compile.

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

		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.

		When  the  application requests a file directory be monitored, a series of FAMEx-
		ists 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 exam-
       ple, 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".

       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 con-
       nection.  It returns 0 if successful and -1 otherwise.

       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 partic-
       ular 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 monitoring the file or directory again.
       Changes which occur while monitoring is suspended are enqueued and delivered when monitor-
       ing 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 regard-
       ing a given request after that request has been suspended.


       When an application is through monitoring a file or directory, it should  call  FAMCancel-
       Monitor.   This routine will signal fam not to monitor this directory anymore.  The FAMRe-
       quest structure is returned from the FAMMonitorFile or FAMMonitorDirectory routines.  FAM-
       CancelMonitor 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 fam socket, and returns it to the appli-
       cation in the form of a FAMEvent.

       FAMNextEvent returns 1 if successful and -1 otherwise.


       The FAMMoved event is not currently supported.

       FAMNextEvent may not initialize the FAMEvent's filename field for FAMEndExist  and  FAMAc-
       knowledge  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.

				      Specialized Libraries				       0a
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 11:28 PM.