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 applications 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 communicate 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
indicates 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
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 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 structure 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
otherwise.
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 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
directories. This is useful when an application is not displaying
information 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
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 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 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. 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.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
