Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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	proce-
	      dures.

       2.     Tell  fam	which files and	directories to monitor by calling FAM-
	      MonitorFile 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 FAMP-
	      ending (or FAMNextEvent) periodically to check the  socket  con-
	      nection  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
       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  FAMSus-
       pendMonitor.

       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 enumera-
       tion 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	direc-
		tory 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	gener-
		ates a FAMAcknowledge event.

       FAMExists
		When the application requests a	file be	monitored, fam	gener-
		ates  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	gener-
       ated  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 file-
       name  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  directo-
       ries.  This is useful when an application is not	displaying information
       about files, when it is iconified, for example.	FAMResumeMonitor  sig-
       nals  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 FAMMon-
       itorDirectory 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  sus-
       pended.

       FAMCancelMonitor

       When  an	 application  is  through  monitoring  a file or directory, it
       should call FAMCancelMonitor.  This routine will	signal fam not to mon-
       itor 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 wait-
       ing.  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  re-
       ceived.	 If  blocking is not desirable,	call FAMPending	before FAMNex-
       tEvent, 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 re-
       turns 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  FA-
       MEndExist  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 ex-
       ecuting the script, typically sh(1) or csh(1).

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

			     Specialized Libraries			    0a

NAME | SYNOPSIS | DESCRIPTION | USING FAM | DATA STRUCTURES | PROCEDURES | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fam&sektion=3x&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help