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;
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 communicate with the application. The fam
process is started when the first connection from any
application to it is opened. It exits after all connec
tions 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 struc
ture 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, respec
tively.
3. Select on the fam socket file descriptor and call
FAMPending when the fam socket is active, and FAM
NextEvent when FAMPending indicates that an event
is available. Alternatively, call FAMPending (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, FAMNex
tEvent 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 moni
toring of a file or directory, it may call FAMSus
pendMonitor. When the application is ready to
start monitoring again, it calls FAMResumeMonitor.
5. Before the application exits, it should call FAM
Close 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. 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 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 con
tains 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 gen
erated when monitoring starts on a nonexistent
file or directory.
FAMStartExecuting
An executable file or shared library being moni
tored 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 run
ning finished. If multiple processes from an
executable are running, this event is only gener
ated when the last one finishes.
FAMCreated
A file was created in a directory being moni
tored. Note: this event is only generated for
files created directly in a directory being moni
tored; subdirectories are not automatically moni
tored.
defined so that programs that reference it will
still compile.
FAMAcknowledge
After a FAMCancelMonitor, fam generates a FAMAc
knowledge event. Also, if an invalid pathname is
specified, fam generates a FAMAcknowledge event.
FAMExists
When the application requests a file be moni
tored, 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 gener
ated as described above. After the last FAMEx
ists message, fam generates a FAMEndExist mes
sage.
If a FAM event applies to a file or directory being moni
tored, 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 con
tains the relative path only. For example, if the direc
tory /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 otherwise.
FAMMonitorDirectory, FAMMonitorFile
FAMMonitorDirectory and FAMMonitorFile tell FAM to start
monitoring a directory or file, respectively. The
ized 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 gener
ated. 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 fam to start moni
toring 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 FAMRe
quest 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 direc
tory, 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
able, 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 applica
tion 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 FAM
NextEvent 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 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.
Man(1) output converted with
man2html