*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> fam (3x)              



FAM(3X)								       FAM(3X)

NAME    [Toc]    [Back]

     fam - File	Alteration Monitor (FAM) library routines

SYNOPSIS    [Toc]    [Back]

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

									Page 1

FAM(3X)								       FAM(3X)

     extern int	FAMErrno;

     extern char *FamErrlist[];

DESCRIPTION    [Toc]    [Back]

     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

     An	application calls routines described here to establish a list of files
     for fam to	monitor.  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.

USING FAM    [Toc]    [Back]

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

DATA STRUCTURES    [Toc]    [Back]

     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.

									Page 2

FAM(3X)								       FAM(3X)

     Use the macro FAMCONNECTION_GETFD to access the file descriptor inside
     the FAMConnection,	rather than accessing it directly.

     The FAMRequest Structure    [Toc]    [Back]

     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

     The FAMEvent Structure    [Toc]    [Back]

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

     FAMMoved FAMMoved events never occur.  The	name remains defined so	that
	      programs that reference 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

									Page 3

FAM(3X)								       FAM(3X)

	      a	directory be monitored,	fam generates a	FAMExists event	for
	      that directory and every file directly contained in that

	      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

     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    [Toc]    [Back]

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

     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

									Page 4

FAM(3X)								       FAM(3X)

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

     FAMCancelMonitor    [Toc]    [Back]

     When an application is through monitoring a file or directory, it should
     call FAMCancelMonitor.  This routine will signal fam 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

     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.

									Page 5

FAM(3X)								       FAM(3X)

     FAMNextEvent returns 1 if successful and -1 otherwise.

SEE ALSO    [Toc]    [Back]


BUGS    [Toc]    [Back]

     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, typically 

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

									PPPPaaaaggggeeee 6666
[ Back ]
 Similar pages
Name OS Title
fam IRIX file alteration monitor
poll HP-UX monitor I/O conditions on multiple file descriptors
sm Tru64 Status monitor directories and file structures
poll HP-UX monitor I/O conditions on multiple file descriptors
state Tru64 Status monitor directories and file structures
poll Tru64 Monitor conditions on multiple file descriptors
statmon Tru64 Status monitor directories and file structures
sm.bak Tru64 Status monitor directories and file structures
bufview IRIX file system buffer cache activity monitor
ups_conf HP-UX HP PowerTrust Uninterruptible Power System (UPS) monitor configuration file
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service