fam.conf(5) [debian man page]
FAM.CONF(5) SGI FAM.CONF(5) NAME
fam.conf - The File Alteration Monitor (FAM) configuration file SYNOPSIS
In addition to its command line options, famd's behavior can also be controlled through its configuration file. By default, this is /etc/fam.conf. The -c command line option can be used to specify an alternate file. FILE FORMAT
Configuration lines are in the format option=value. Lines beginning with # or ! are ignored. famd recognizes the following options: insecure_compatibility If set to true, this disables authentication and reduces access security as described under SECURITY below. This is false by default. Setting this option to true is the same as using the -C command line option. untrusted_user This is the user name or UID of the user account which famd will use for unauthenticated clients. If a file can't be stated by this user, famd will not tell unauthenticated clients about the file's existence. If an untrusted user is not given in the configuration file, famd will write an error message to the system log and terminate. local_only If set to true, famd will ignore requests from remote famds. This is false by default. Setting this option to true is the same as using the -L command line option. This option is ignored if famd is started by inetd. idle_timeout This is the time in seconds that famd will wait before exiting after its last client disconnects. The default is 5 seconds. This option is overridden by the -T command line option. nfs_polling_interval This is the interval in seconds between polling files over an NFS filesystem. The default is 6 seconds. This option is overridden by the -t command line option. xtab_verification If set to true, famd will check the list of exported filesystems when remote requests are received to verify that the requests fall on filesystems which are exported to the requesting hosts. This is true by default. If this option is set to false, famd will service remote requests without attempting to perform the verification. If the local_only configuration option or -L command line option is used, xtab_verification has no effect. detect_readonly_filesystems If set to true, famd will try to detect read-only filesystems. Such filesystems are assumed to never change. This is false by default. Setting this option to true is the same as using the -r command line option. SEE ALSO
fam.conf (fam 2.6.10) January 19, 2003 FAM.CONF(5)
Check Out this Related Man Page
FAM(3) SGI FAM(3) NAME
fam - File Alteration Monitor (FAM) library routines SYNOPSIS
#include <fam.h> extern int FAMOpen(FAMConnection* fc); extern int FAMOpen2(FAMConnection* fc, const char* appName); 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, the File Alteration Monitor, is a subsystem that applications can use to be notified when specific files or directories are changed. It is intended as a replacement for mechanisms such as poll and select. FAM comes in two parts: famd, the daemon that listens for requests and provides notifications, and libfam a library that client applica- tions can use to communicate with FAM. libfam's routines are found in libfam.a, which is loaded if the option -lfam is used with cc or ld. An application calls routines described here to establish a list of files for famdto monitor. famdgenerates events on a socket to communi- cate with the application. The famd process is started when the first connection from any application to it is opened. It exits after all connections to it have been closed. USAGE
Here are the steps required to use FAM in an application: 1. Create a connection to famd by calling FAMOpen. This routine will pass back a FAMConnection structure used in all FAM procedures. 2. Tell famd which files and directories to monitor by calling FAMMonitorFile and FAMMonitorDirectory to express interest in files and directories, respectively. 3. Select on the famd socket file descriptor and call FAMPending when the famd socket is active, and FAMNextEvent when FAMPending indi- cates that an event is available. Alternatively, call FAMPending (or FAMNextEvent) periodically to check the socket connection to famd 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 tempo- rarily 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 famd. DATA STRUCTURES
The FAMConnection Structure The FAMConnection data structure is created when opening a connection to famd. 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 famd 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 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. FAMMoved FAMMoved events never occur. The name remains defined so that programs that reference it will still compile. FAMAcknowledge After a FAMCancelMonitor, famd generates a FAMAcknowledge event. Also, if an invalid pathname is specified, famd generates a FAMAcknowledge event. FAMExists When the application requests a file be monitored, famd generates a FAMExists event for that file. When the application requests a directory be monitored, famd 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, famd 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 famd. If an event applies to an entry in a monitored directory, the filename field contains the relative path only. For example, if the directory /tmp/xyzzy were monitored, and the file /tmp/xyzzy/plugh were deleted, a FAMDeleted event would be generated containing "plugh" in filename. If the directory itself were deleted, filename would contain "/tmp/xyzzy". PROCEDURES
FAMOpen, FAMClose The application opens a connection to famd by calling FAMOpen. FAMOpen initializes the FAMConnection structure passed in to it and returns 0 if successful, otherwise -1. The parameter appName of FAMOpen2 should be set to the name of your application. The FAMConnection struc- ture is passed to all subsequent FAM procedure calls. FAMClose frees resources associated with files still being monitored and closes a famd connection. It returns 0 if successful and -1 oth- erwise. FAMMonitorDirectory, FAMMonitorFile FAMMonitorDirectory and FAMMonitorFile tell famd 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 mod- ified 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 directories. This is useful when an application is not displaying informa- tion about files, when it is iconified, for example. FAMResumeMonitor signals famd 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 famd 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 finished monitoring a file or directory, it should call FAMCancelMonitor. This routine will signal famd not to mon- itor this directory anymore. The FAMRequest structure is returned from the FAMMonitorFile or FAMMonitorDirectory routines. FAMCancelMoni- tor 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 rou- tine 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 famd socket, and returns it to the application in the form of a FAMEvent. FAMNextEvent returns 1 if successful and -1 otherwise. SEE ALSO
famd(8), fstat(2), poll(2), select(2) 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 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 executing the script. Each process is limited to 1000 active requests at a time. When using the Linux DNotify kernel monitor, a file handle will be opened for each file famd is asked to monitor, meaning the file system the file resides on can not be unmounted. fam (fam 2.6.10) January 19, 2003 FAM(3)