Annotation of fam/man/fam.3x, Revision 1.1.1.1
1.1 trev 1: '\"macro stdmacro
2: .if n .pH g3x.fam @(#)fam 30.3 of 1/19/86
3: .nr X
4: .if \nX=0 .ds x} FAM 3X "Specialized Libraries" "\&"
5: .if \nX=1 .ds x} FAM 3X "Specialized Libraries"
6: .if \nX=2 .ds x} FAM 3X "" "\&"
7: .if \nX=3 .ds x} FAM "" "" "\&"
8: .TH \*(x}
9: .SH NAME
10: fam \- File Alteration Monitor (FAM) library routines
11: .SH SYNOPSIS
12: .nf
13: .B #include <fam.h>
14: .P
15: .B "extern int FAMOpen(FAMConnection* fc);"
16: .PP
17: .B "extern int FAMClose(FAMConnection* fc);"
18: .PP
19: .B "extern int FAMMonitorDirectory(FAMConnection *fc,"
20: .B " char *filename,"
21: .B " FAMRequest* fr,"
22: .B " void* userData);"
23: .PP
24: .B "extern int FAMMonitorFile(FAMConnection *fc,
25: .B " char *filename,"
26: .B " FAMRequest* fr,"
27: .B " void* userData);"
28: .PP
29: .B "int FAMSuspendMonitor(FAMConnection *fc, FAMRequest *fr);"
30: .PP
31: .B "int FAMResumeMonitor(FAMConnection *fc, FAMRequest *fr);"
32: .PP
33: .B "int FAMCancelMonitor(FAMConnection *fc, FAMRequest *fr);"
34: .PP
35: .B "int FAMNextEvent(FAMConnection *fc, FAMEvent *fe);"
36: .PP
37: .B "int FAMPending(FAMConnection* fc);"
38: .PP
39: .B "typedef struct {"
40: .B " int fd;"
41: .B "} FAMConnection;"
42: .PP
43: .B "#define FAMCONNECTION_GETFD(fc) (fc->fd)"
44: .PP
45: .B "typedef struct {"
46: .B " int reqnum;"
47: .B "} FAMRequest;"
48: .PP
49: .B "enum FAMCodes { FAMChanged=1, FAMDeleted=2, FAMStartExecuting=3, "
50: .B " FAMStopExecuting=4, FAMCreated=5, FAMMoved=6, FAMAcknowledge=7,"
51: .B " FAMExists=8, FAMEndExist=9 };"
52: .PP
53: .B "typedef struct {"
54: .B " FAMConnection* fc;"
55: .B " FAMRequest fr;"
56: .B " char hostname[MAXHOSTNAMELEN];"
57: .B " char filename[NAME_MAX];"
58: .B " void *userdata;"
59: .B " FAMCodes code;"
60: .B "} FAMEvent;"
61: .PP
62: .B "extern int FAMErrno;"
63: .PP
64: .B "extern char *FamErrlist[];"
65: .PP
66: .SH DESCRIPTION
67: \fIFAM\fP monitors files and directories, notifying interested
68: applications of changes. Routines for communicating with the fam(1M)
69: server process are found in ``libfam.a'', which is loaded if the
70: option ``-lfam'' is used with cc(1) or ld(1). The library
71: ``libC.a'' (``-lC'') must also be specified.
72: .PP
73: An application calls routines described here to establish a list of
74: files for \fIfam \fPto monitor. \fIFam \fPgenerates events on a socket to
75: communicate with the application. The \fIfam\fP process is started when
76: the first connection from any application to it is opened. It exits
77: after all connections to it have been closed.
78: .PP
79: .SH USING FAM
80: Here are the steps required to use \fIFAM \fPin an application:
81: .PP
82: .AL
83: .LI
84: .IP 1.
85: Create a connection to \fIfam\fP by calling FAMOpen. This routine
86: will pass back a FAMConnection structure used in all \fIfam \fP
87: procedures.
88: .IP 2.
89: Tell \fIfam\fP which files and directories to monitor by calling
90: FAMMonitorFile and FAMMonitorDirectory to express interest in
91: files and directories, respectively.
92: .IP 3.
93: Select on the \fIfam\fP socket file descriptor and call
94: FAMPending when the \fIfam \fPsocket is active, and FAMNextEvent when
95: FAMPending indicates that an event is available. Alternatively,
96: call FAMPending (or FAMNextEvent)
97: periodically to check the socket connection to \fIfam\fP to see
98: if any new information has arrived. If there are no events
99: pending, FAMNextEvent blocks until an event occurs.
100: .IP 4.
101: When the application is through monitoring a file or directory, it
102: should call FAMCancelMonitor. If the application wants to
103: temporarily suspend monitoring of a file or directory, it may call
104: FAMSuspendMonitor. When the application is ready to start
105: monitoring again, it calls FAMResumeMonitor.
106: .IP 5.
107: Before the application exits, it should call FAMClose to free
108: resources associated with files still being monitored and to close the
109: connection to \fIfam.\fP
110: .PP
111: .SH DATA STRUCTURES
112: .B "The FAMConnection Structure"
113: .PP
114: The FAMConnection data structure is created when opening a connection
115: to \fIFAM.\fP Subsequently it is passed into all \fIFAM \fPprocedures. This
116: structure has all the information in it to communicate to \fIfam\fP.
117: .PP
118: Use the macro FAMCONNECTION_GETFD to access the file descriptor inside the
119: FAMConnection, rather than accessing it directly.
120: .PP
121: .B "The FAMRequest Structure"
122: .PP
123: When \fIfam\fP is called on to monitor a file, it passes back a
124: FAMRequest structure. This structure uniquely identifies the request
125: so that it may be cancelled, using FAMCancelMonitor
126: or suspended, using FAMSuspendMonitor.
127: .PP
128: .B "The FAMEvent Structure"
129: .PP
130: Changes to files and directories are encoded in the FAMEvent
131: structure. The \fIcode \fPfield of this structure contains one of the
132: following enumeration constants:
133: .TP .90i
134: .SM FAMChanged
135: Some value which can be obtained with fstat(1) changed for a file or
136: directory being monitored.
137: .TP
138: .SM FAMDeleted
139: A file or directory being monitored was deleted or its name was changed.
140: This event is also generated when monitoring starts on a nonexistent file or directory.
141: .TP
142: .SM FAMStartExecuting
143: An executable file or shared library
144: being monitored started executing. If multiple processes execute
145: the same file, this event only occurs when the first process starts.
146: .TP
147: .SM FAMStopExecuting
148: An executable file being monitored which was running finished. If
149: multiple processes from an executable are running, this event is only
150: generated when the last one finishes.
151: .TP
152: .SM FAMCreated
153: A file was created in a directory being monitored. Note: this event
154: is only generated for files created directly in a directory being
155: monitored; subdirectories are not automatically monitored.
156: .TP
157: .SM FAMMoved
158: FAMMoved events never occur. The name remains defined so that
159: programs that reference it will still compile.
160: .TP
161: .SM FAMAcknowledge
162: After a FAMCancelMonitor, \fIfam \fPgenerates a FAMAcknowledge event.
163: Also, if an invalid pathname is specified, \fIfam \fP generates a
164: FAMAcknowledge event.
165: .TP
166: .SM FAMExists
167: When the application requests a file be monitored, \fIfam\fP
168: generates a FAMExists event for that file. When the application
169: requests a directory be monitored, \fIfam\fP generates a FAMExists
170: event for that directory and every file directly contained in that
171: directory.
172: .TP
173: .SM FAMEndExist
174: When the application requests a file directory be monitored, a series of
175: FAMExists events is generated as described above. After the last
176: FAMExists message, \fIfam \fPgenerates a FAMEndExist message.
177: .PP
178: If a FAM event applies to a file or directory being monitored, the
179: FAMEvent's \fIfilename \fPfield contains the full pathname
180: that was passed to fam.
181: If an event applies to an entry in a monitored directory, the
182: \fIfilename \fPfield contains the relative path only. For
183: example, if the directory \fI/usr/tmp/xyzzy \fPwere monitored,
184: and the file \fI/usr/tmp/xyzzy/plugh \fP were deleted, a FAMDeleted
185: event would be generated containing "plugh" in \fIfilename\fP.
186: If the directory itself were deleted, \fIfilename \fPwould contain
187: "/usr/tmp/xyzzy".
188: .\".SH ERROR HANDLING
189: .\"If an error occurs inside of \fIFAM, \fPa global named FAMErrno is set to a
190: .\"non-zero value and the routine that generated the error in will return an error
191: .\"value. The value of FAMErrno is valid until the next \fIFAM \fProutine is
192: .\"called. The FAMErrno can be translated in to a character string using the
193: .\"global array FAMErrlist.
194: .PP
195: .SH PROCEDURES
196:
197: .B "FAMOpen, FAMClose"
198: .PP
199: The application opens a connection to \fIfam \fPby calling FAMOpen. FAMOpen
200: initializes the FAMConnection structure passed in to it and returns 0 if
201: successful, otherwise -1. The variable char* appName should be set to the
202: name of your application. The FAMConnection structure is passed to all
203: subsequent \fIFAM \fPprocedure calls.
204:
205: FAMClose frees resources associated with files still being monitored and closes
206: a \fIfam \fPconnection. It returns 0 if successful and -1 otherwise.
207: .PP
208: .B "FAMMonitorDirectory, FAMMonitorFile"
209: .PP
210: FAMMonitorDirectory and FAMMonitorFile tell \fIFAM \fPto start
211: monitoring a directory or file, respectively. The parameters to this
212: function are a FAMConnection (initialized by FAMOpen), a FAMRequest
213: structure, a filename and a user data pointer. The FAMRequest
214: structure is modified to subsequently identify this request. When
215: the file or directory changes, a \fIFAM \fPevent structure will be
216: generated. The application can retrieve this structure by calling
217: FAMNextEvent (see description under FAMNextEvent).
218: .PP
219: FAMMonitorDirectory monitors changes that happens to the contents of the
220: directory (as well as the directory file itself); FAMMonitorFile monitors only
221: what happens to a particular file. Both routines return 0 if successful and -1
222: otherwise.
223: .PP
224: The filename argument must be a full pathname.
225:
226: .B "FAMSuspendMonitor, FAMResumeMonitor"
227: .PP
228: FAMSuspendMonitor temporarily suspends monitoring of files or directories.
229: This is useful when an application is not displaying information about files,
230: when it is iconified, for example. FAMResumeMonitor signals \fIfam \fPto
231: start monitoring the file or directory again. Changes which occur while
232: monitoring is suspended are enqueued and delivered when monitoring is
233: resumed.
234: .PP
235: Both of these routines take a FAMConnection and a FAMRequest structure.
236: The FAMRequest Structure is returned from the FAMMonitorFile or
237: FAMMonitorDirectory routines and return 0 if successful and -1 otherwise.
238: .PP
239: Because fam runs as an asynchronous process, FAMNextEvent may return
240: a few events regarding a given request after that request has been suspended.
241:
242: .B "FAMCancelMonitor"
243: .PP
244: When an application is through monitoring a file or directory, it should
245: call FAMCancelMonitor. This routine will signal \fIfam \fPnot to monitor
246: this directory anymore. The FAMRequest structure is returned from the
247: FAMMonitorFile or FAMMonitorDirectory routines. FAMCancelMonitor returns 0 if
248: successful and -1 otherwise.
249: .PP
250:
251: .B "FAMPending, FAMNextEvent"
252: .PP
253: FAMPending returns 1 if an event is waiting and 0 if no event is waiting. It
254: also returns 1 if an error has been encountered. This routine returns
255: immediately to the caller.
256: .PP
257: FAMNextEvent will get the next \fIFAM \fPevent. If there are no \fIFAM
258: \fPevents waiting, then the calling application blocks until a \fIFAM \fPevent
259: is received. If blocking is not desirable, call FAMPending before
260: FAMNextEvent, and only call FAMNextEvent when FAMPending says an event is
261: available.
262: .PP
263: There are two ways to for applications to receive \fIFAM \fPevents:
264: .PP
265: .AL
266: .LI
267: 1. The Select approach - The application selects on the file
268: descriptor returned from FAMOpen, in the FAMConnection structure.
269: When this file descriptor becomes active, the application calls
270: FAMPending to determine whether a complete event is ready, and
271: FAMNextEvent to retrieve the pending \fIFAM \fPevent.
272: .PP
273: 2. The Polling approach - The application calls FAMPending
274: periodically (usually when the system is waiting for input).
275: When FAMPending returns 1, the application calls FAMNextEvent to
276: retrieve the pending \fIFAM \fP event.
277: .PP
278: FAMNextEvent reads any information that is on the \fIfam \fPsocket,
279: and returns it to the application in the form of a FAMEvent.
280: .PP
281: FAMNextEvent returns 1 if successful and -1 otherwise.
282:
283:
284: .SH SEE ALSO
285: fam(1M).
286: .SH BUGS
287: The FAMMoved event is not currently supported.
288: .PP
289: FAMNextEvent may not initialize the FAMEvent's filename field
290: for FAMEndExist and FAMAcknowledge events.
291: Use the request number to determine the file or directory
292: to which those events refer.
293: .PP
294: FAMErrno and FamErrlist are not set when errors occur.
295: .PP
296: When a shell script is run, notification is generated for the shell
297: executing the script, typically sh(1) or csh(1).
298: .PP
299: Each process is limited to 1000 active requests at a time.
300:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to fam.3x CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [Development] / fam / man