FAM(1M) FAM(1M)
NAME
fam - file alteration monitor
SYNOPSIS
/usr/etc/fam [ -t NFS polling interval ]
DESCRIPTION
Fam is a server that tracks changes to the file system and relays these
changes to interested applications. Applications such as WorkSpace(1G)
and Mailbox(1G) present an up-to-date view of the file system. In the
absence of fam, these applications and others like them would be forced
to poll the file system to detect changes. Fam is considerably more
efficient.
Applications can request fam to monitor any files or directories in the
file system. When fam detects changes to these files, it notifies the
appropriate application. Fam(3X) provides a programmatic interface to
fam.
Fam is informed of file system changes as they happen by the IRIX kernel
through the imon(1M) pseudo device driver. Currently, fam servers do not
communicate with each other and consequently, they poll to determine the
state of NFS mounted file systems. The -t option specifies the polling
interval in seconds. The default polling interval is 3 seconds. Since
fam is invoked by inetd(1M), you must edit the /etc/inetd.conf file to
change the polling interval.
SEE ALSO
imon(1M), fam(3X), inetd(1M), workspace(1G), mailbox(1G)
fam(1M) fam(1M)
NAME
fam - file alteration monitor
SYNOPSIS
/usr/etc/fam [ -f | -v | -d ] [ -l ] [ -t NFS_polling_interval ]
[ -T idle_timeout ] [ -p program.version ]
DESCRIPTION
fam is a server that tracks changes to the filesystem and relays these
changes to interested applications. Applications such as fm(1G) and
mailbox(1) present an up-to-date view of the filesystem. In the absence
of fam, these applications and others like them are forced to poll the
filesystem to detect changes. fam is more efficient.
Applications can request fam to monitor any files or directories in the
filesystem. When fam detects changes to these files, it notifies the
appropriate application. fam(3X) provides a programmatic interface to
fam.
fam is informed of filesystem changes as they happen by the IRIX kernel
through the imon(7M) pseudo device driver. If asked to monitor files on
an NFS mounted filesystem, fam tries to use fam on the NFS server to
monitor files. If fam cannot contact a remote fam, it polls the files
instead. fam also polls special files.
Normally, fam is started by inetd(1M). It is registered with portmap(1M)
as performing the sgi_fam service.
-l Disable polling of NFS files. It does not
disable use of remote fam on NFS servers, nor
does it disable polling of local files.
-t NFS_polling_interval Set the interval for polling files to
NFS_polling_interval seconds. The default is
six seconds.
-T idle_timeout Set the idle timeout interval to idle_timeout.
Fam exits idle_timeout seconds after its last
client disconnects. The default is five
seconds.
-f If fam is not started by inetd, it remains in
the foreground instead of spawning a child and
exiting.
-v Turn on verbose messages.
-d Enable verbose messages and debug messages.
-p program.version Use the specified RPC program and version
numbers.
Page 1
fam(1M) fam(1M)
SEE ALSO
fm(1G), inetd(1M), mailbox(1), portmap(1M), fam(3X), imon(7M).
FAM(3X) FAM(3X)
NAME
fam - File Alteration Monitor (FAM) library routines
SYNOPSIS
#include
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);
extern int FAMMonitorRemoteDirectory(FAMConnection *fc,
char *hostname,
char *filename,
FAMRequest* fr,
void* userdata);
extern int FAMMonitorRemoteFile(FAMConnection *fc,
char *hostname,
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;
Page 1
FAM(3X) FAM(3X)
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 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
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
FAMNextEvent when the fam socket is active. Alternatively,
the application must call FAMNextEvent (or FAMPending)
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
Page 2
FAM(3X) FAM(3X)
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
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.
FAMStartExecuting
An executable file being monitored started executing. This
event occurs every time the file is run, even if older processes
are still running.
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.
Page 3
FAM(3X) FAM(3X)
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.
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 directory be monitored, a series
of FAMExists events are generated as described above. After the
last FAMExists message, fam generates a FAMEndExist messsage.
ERROR HANDLING
If an error occurs inside of FAM, a global named FAMErrno is set to a
non-zero value and the routine that generated the error in will return an
error value. The value of FAMErrno is valid until the next FAM routine
is called. The FAMErrno can be translated in to a character string using
the global array FAMErrlist.
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 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.
Page 4
FAM(3X) FAM(3X)
The filename argument must be a full pathname.
FAMMonitorRemoteDirectory, FAMMonitorRemoteFile
FAMMonitorRemoteDirectory and FAMMonitorRemoteFile are analogous to
FAMMonitorDirectory and FAMMonitorFile. They take an additional hostname
parameter (as returned by gethostname(2), for example) to connect to a
fam process running on a remote processor. Both routines return 0 if
successful and -1 otherwise.
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 discarded,
not enqueued.
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.
FAMCancelMonitor
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 waiting, 0 if no event is waiting, and
-1 if there is an error. This routine returns immediately to the caller.
FAMNextEvent will get the next FAM event (file or directory change). If
there are no FAM events waiting, then the calling application blocks
until a FAM event is received (from fam).
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
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 with a positive return value, the
application calls FAMNextEvent to retrieve the pending FAM
Pevents.
Page 5
FAM(3X) FAM(3X)
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.
The current fam does not support networking. FAMMonitorRemoteDirectory
and FAMMonitorRemoteFile are not implemented yet.
The FAMErrno variable is 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.
FAM(3X) FAM(3X)
NAME
fam - File Alteration Monitor (FAM) library routines
SYNOPSIS
#include
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);
extern int FAMMonitorRemoteDirectory(FAMConnection *fc,
char *hostname,
char *filename,
FAMRequest* fr,
void* userdata);
extern int FAMMonitorRemoteFile(FAMConnection *fc,
char *hostname,
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;
Page 1
FAM(3X) FAM(3X)
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 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
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 FAMNextEvent when
the fam socket is active. Alternatively, the application must call
FAMNextEvent (or FAMPending) 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.
Page 2
FAM(3X) FAM(3X)
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.
Page 3
FAM(3X) FAM(3X)
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
messsage.
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".
ERROR HANDLING
If an error occurs inside of FAM, a global named FAMErrno is set to a
non-zero value and the routine that generated the error in will return an
error value. The value of FAMErrno is valid until the next FAM routine
is called. The FAMErrno can be translated in to a character string using
the global array FAMErrlist.
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
Page 4
FAM(3X) FAM(3X)
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.
FAMMonitorRemoteDirectory, FAMMonitorRemoteFile
FAMMonitorRemoteDirectory and FAMMonitorRemoteFile are obsolete. Remote
files and directories on mounted NFS filesystems may be monitored using
FAMMonitorDirectory and FAMMonitorFile. There is not supported way to
monitor files or directories that are not mounted.
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 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 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
Page 5
FAM(3X) FAM(3X)
FAMPending returns 1 if an event waiting, 0 if no event is waiting, and
-1 if there is an error. This routine returns immediately to the caller.
FAMNextEvent will get the next FAM event (file or directory change). If
there are no FAM events waiting, then the calling application blocks
until a FAM event is received (from fam).
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
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 with a positive return value, the
application calls FAMNextEvent to retrieve the pending FAM
Pevents.
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.
The FAMErrno variable is 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.
Schneider Lab.
origin: 1997 April 18
updated: 1998 Jan 8