Gamin
From Docunext Technology Wiki
Gamin doesn't have much documentation yet so here's some from FAM:
NAME
fam - File Alteration Monitor (FAM) library routines
SYNOPSIS
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 FAMCon‐
nection structure used in all fam procedures.
2. Tell fam which files and directories to monitor by calling FAMMonitorFile and FAMMoni‐
torDirectory 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. Alter‐
natively, call FAMPending (or FAMNextEvent) periodically to check the socket connec‐
tion to fam to see if any new information has arrived. If there are no events pend‐
ing, FAMNextEvent blocks until an event occurs.
4. When the application is through monitoring a file or directory, it should call FAM‐
CancelMonitor. 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 commu‐
nicate 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 struc‐
ture 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 pro‐
cesses 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 gener‐
ated 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 refer‐
ence 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 gener‐
ates 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 gen‐
erates 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 mon‐
itored 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".
PROCEDURES
FAMOpen, FAMClose
The application opens a connection to fam by calling FAMOpen. FAMOpen initializes the FAM‐
Connection 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 connec‐
tion. 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 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 FAMNex‐
tEvent (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 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 FAMCancelMoni‐
tor. This routine will signal fam not to monitor this directory anymore. The FAMRequest
structure is returned from the FAMMonitorFile or FAMMonitorDirectory routines. FAMCancel‐
Monitor 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 call‐
ing 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 fam socket, and returns it to the applica‐
tion 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 FAMAcknowl‐
edge 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).
This text is licensed under the GPL as part of the fam package downloaded from the GNU Savannah FAM page.