Annotation of fam/man/fam.3x, Revision 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