Annotation of fam/include/fam.h, Revision 1.1
1.1 ! trev 1: /*
! 2: Copyright (C) 1999 Silicon Graphics, Inc. All Rights Reserved.
! 3:
! 4: This program is free software; you can redistribute it and/or modify it
! 5: under the terms of version 2.1 of the GNU Lesser General Public License
! 6: as published by the Free Software Foundation.
! 7:
! 8: This program is distributed in the hope that it would be useful, but
! 9: WITHOUT ANY WARRANTY; without even the implied warranty of
! 10: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Further, any
! 11: license provided herein, whether implied or otherwise, is limited to
! 12: this program in accordance with the express provisions of the GNU Lesser
! 13: General Public License. Patent licenses, if any, provided herein do not
! 14: apply to combinations of this program with other product or programs, or
! 15: any other product whatsoever. This program is distributed without any
! 16: warranty that the program is delivered free of the rightful claim of any
! 17: third person by way of infringement or the like. See the GNU Lesser
! 18: General Public License for more details.
! 19:
! 20: You should have received a copy of the GNU General Public License along
! 21: with this program; if not, write the Free Software Foundation, Inc., 59
! 22: Temple Place - Suite 330, Boston MA 02111-1307, USA.
! 23: */
! 24:
! 25: #ifndef _FAM_
! 26: #define _FAM_
! 27: #ifdef __cplusplus
! 28: extern "C" {
! 29: #endif
! 30:
! 31:
! 32: /*****************************************************************************
! 33: *
! 34: * MODULE: Fam.h - File Alteration Monitor
! 35: *
! 36: * Fam allows applications to monitor files - receiving events when they
! 37: * change. The scheme is simple: Applications register which
! 38: * files/directories they are interested, and fam will notify the
! 39: * application when any of these files are changed.
! 40: *
! 41: *****************************************************************************/
! 42:
! 43: /* For NAME_MAX - maximum # of chars in a filename */
! 44: #include "limits.h"
! 45:
! 46:
! 47:
! 48:
! 49:
! 50: /*****************************************************************************
! 51: * DATA STRUCTURES
! 52: *
! 53: *
! 54: * FAMConnection Structure:
! 55: *
! 56: * The FAMConnection Data structure is created when opening a connection
! 57: * to fam. After that, it is passed into all fam procedures. This
! 58: * structure has all the information in it to talk to fam (Currently,
! 59: * the only data inside this structure is a file descriptor for
! 60: * the socket to fam).
! 61: *****************************************************************************/
! 62:
! 63: typedef struct FAMConnection {
! 64: int fd;
! 65: void *client;
! 66: } FAMConnection;
! 67:
! 68:
! 69: /*****************************************************************************
! 70: * To access the fd inside this structure (so the application writer can
! 71: * use select for fam events), the following macro is defined (this will
! 72: * allow us to change the implementation without users having to change
! 73: * their code):
! 74: *****************************************************************************/
! 75: #define FAMCONNECTION_GETFD(fc) ((fc)->fd)
! 76:
! 77:
! 78:
! 79:
! 80:
! 81: /*****************************************************************************
! 82: * FAMRequest Structure:
! 83: *
! 84: * Every time fam is called on to monitor a file, it passes back a
! 85: * FAMRequest structure. The main piece of data that this structure
! 86: * contans is a reqnum. This reqnum is guaranteed to be unique. When
! 87: * cancelling or suspending a monitor request, you must pass this
! 88: * data structure into FAMCancelMonitor or FAMSuspendMonitor to
! 89: * make sure that you are cancelling/suspending the correct request
! 90: * (You can monitor the same file/directory more than once).
! 91: *****************************************************************************/
! 92:
! 93: typedef struct FAMRequest {
! 94: int reqnum;
! 95: } FAMRequest;
! 96:
! 97:
! 98: /*****************************************************************************
! 99: * Once again, to access the reqnum inside this structure, use the
! 100: * following macro:
! 101: *****************************************************************************/
! 102: #define FAMREQUEST_GETREQNUM(fc) ((fc)->reqnum)
! 103:
! 104:
! 105:
! 106: /*****************************************************************************
! 107: * FAMEvent Structure:
! 108: *
! 109: * When a file/directory has been modified/deleted, fam will pass
! 110: * a FAMEvent structure to the application (through the callback
! 111: * in the FAMMonitorFile/Directory routines). This structure will
! 112: * describe what event happened to the file. The different events
! 113: * that can happen to a file are listed in the FAMCodes enum.
! 114: *****************************************************************************/
! 115: enum FAMCodes { FAMChanged=1, FAMDeleted=2, FAMStartExecuting=3,
! 116: FAMStopExecuting=4, FAMCreated=5, FAMMoved=6,
! 117: FAMAcknowledge=7, FAMExists=8, FAMEndExist=9 };
! 118:
! 119: typedef struct FAMEvent {
! 120: FAMConnection* fc; /* The fam connection that event occurred on */
! 121: FAMRequest fr; /* Corresponds to the FamRequest from monitor */
! 122: char *hostname; /* host and filename - pointer to which */
! 123: char filename[PATH_MAX]; /* file changed */
! 124: void *userdata; /* userdata associated with this monitor req. */
! 125: enum FAMCodes code; /* What happened to file - see above */
! 126: } FAMEvent;
! 127:
! 128:
! 129:
! 130:
! 131:
! 132: /*****************************************************************************
! 133: * ERROR HANDLING
! 134: *
! 135: * If an error occurs inside of libfam, a global named FAMErrno is set
! 136: * to a non-zero value and the routine that the error occurred in will
! 137: * return an error value (usually NULL). FAMErrlist is a global
! 138: * string array (indexed by FAMErrno) that describes the last error
! 139: * that happened;
! 140: *
! 141: * NOTE: currently FAMErrno and FamErrList are unused
! 142: *****************************************************************************/
! 143:
! 144: extern int FAMErrno;
! 145: extern char *FamErrlist[];
! 146:
! 147: /*
! 148: *[NOTE: Eventually, there will be a bunch of defines right here defining what
! 149: * errors can happen in using libfam ]
! 150: */
! 151:
! 152:
! 153:
! 154:
! 155:
! 156:
! 157: /*****************************************************************************
! 158: * PROCEDURES:
! 159: *
! 160: * FAMOpen, FAMClose
! 161: *
! 162: * The first step that an application has to do is open a connection to
! 163: * fam. This is done through the FAMOpen. FAMOpen returns a FAMConnection
! 164: * data structure which is passed to all fam procedures. FAMClose closes
! 165: * a fam connection.
! 166: *
! 167: * On error, FAMOpen will return NULL and FAMClose will return -1 (and
! 168: * FAMErrno will be set to the value of the error).
! 169: *****************************************************************************/
! 170:
! 171: extern int FAMOpen(FAMConnection* fc);
! 172: extern int FAMOpen2(FAMConnection* fc, const char* appName);
! 173: extern int FAMClose(FAMConnection* fc);
! 174:
! 175:
! 176:
! 177: /*****************************************************************************
! 178: * FAMMonitorDirectory, FAMMonitorFile
! 179: *
! 180: * These routines tell fam to start monitoring a file/directory. The
! 181: * parameters to this function are a FAMConnection (received from FAMOpen),
! 182: * a filename and a user data ptr. A FAMRequest structure is returned.
! 183: * When the file/directory changes, a fam event structure will be
! 184: * generated. The application can retrieve this structure by calling
! 185: * FAMNextEvent (see description under FAMNextEvent).
! 186: *
! 187: * The difference between these two routines is that FAMMonitorDirectory
! 188: * monitors any changes that happens to the contents of the directory
! 189: * (as well as the directory file itself) and FAMMonitorFile monitors
! 190: * only what happens to a particular file.
! 191: *
! 192: * On error FAMMonitorDirectory/File will return NULL (and FAMErrno will
! 193: * be set to the value of the error).
! 194: *****************************************************************************/
! 195:
! 196: extern int FAMMonitorDirectory(FAMConnection *fc,
! 197: const char *filename,
! 198: FAMRequest* fr,
! 199: void* userData);
! 200: extern int FAMMonitorFile(FAMConnection *fc,
! 201: const char *filename,
! 202: FAMRequest* fr,
! 203: void* userData);
! 204: extern int FAMMonitorCollection(FAMConnection *fc,
! 205: const char *filename,
! 206: FAMRequest* fr,
! 207: void* userData,
! 208: int depth,
! 209: const char* mask);
! 210:
! 211: extern int FAMMonitorDirectory2(FAMConnection *fc,
! 212: const char *filename,
! 213: FAMRequest* fr);
! 214: extern int FAMMonitorFile2(FAMConnection *fc,
! 215: const char *filename,
! 216: FAMRequest* fr);
! 217:
! 218:
! 219: /*****************************************************************************
! 220: * FAMSuspendMonitor, FAMResumeMonitor
! 221: *
! 222: * FAMSuspendMonitor enables applications to suspend
! 223: * receive events about files/directories that are changing. This can
! 224: * be useful in situations when an application is stowed and does not
! 225: * want to receive events until it is unstowed. FAMResumeMonitor
! 226: * signals fam to start monitoring the file/directory again.
! 227: *
! 228: * Both of these routines take a FAMConnection and a FAMRequest structure.
! 229: * The FAMRequest Structure is returned from the FAMMonitorFile/Directory
! 230: * routines.
! 231: *
! 232: * On error, FAMResume/SuspendMonitor will return -1 (and the global
! 233: * FAMErrno will be set to the value of the error).
! 234: *****************************************************************************/
! 235:
! 236: int FAMSuspendMonitor(FAMConnection *fc, const FAMRequest *fr);
! 237: int FAMResumeMonitor(FAMConnection *fc, const FAMRequest *fr);
! 238:
! 239:
! 240:
! 241:
! 242:
! 243:
! 244: /*****************************************************************************
! 245: * FAMCancelMonitor
! 246: *
! 247: * When an application is done monitoring a file/directory, it should
! 248: * call FAMCancelMonitor. This routine will signal fam not to watch
! 249: * this directory anymore. Once again, the FAMRequest structure is
! 250: * returned from the FAMMonitorFile/Directory routines.
! 251: *
! 252: * On error, FAMCancelMonitor will return -1 (and the global
! 253: * FAMErrno will be set to the value of the error). This routine will free
! 254: * the FAMRequest structure that is passed in.
! 255: *****************************************************************************/
! 256:
! 257: int FAMCancelMonitor(FAMConnection *fc, const FAMRequest *fr);
! 258:
! 259:
! 260:
! 261:
! 262: /*****************************************************************************
! 263: * FAMNextEvent, FAMPending
! 264: *
! 265: * FAMNextEvent will get the next fam event (file/directory change). If
! 266: * there are no fam events waiting, then FAMNextEvent will wait
! 267: * until a fam event has been received (from fam).
! 268: *
! 269: * FAMPending will return the number of fam events that are waiting.
! 270: * This routine always returns immediately to the caller.
! 271: *
! 272: * Essentially, there are two ways to for applications to receive fam
! 273: * events:
! 274: *
! 275: * 1. The "Polling" approach - Just call FAMPending periodically;
! 276: * like when the system is waiting for input. If FAMPending returns
! 277: * with a positive return value, then there are fam events waiting.
! 278: * Call FAMNextEvent to receive the events.
! 279: *
! 280: * 2. The "Select" approach - Use the fd returned from famOpen (in the
! 281: * FAMConnection structure) as one of the fds that the application
! 282: * selects on. When select returns saying that data is on the fam
! 283: * fd, call FAMNextEvent.
! 284: *
! 285: * FAMNextEvent reads any information that is on the fam socket,
! 286: * and returns it to the application (in the form of a FAMEvent).
! 287: *
! 288: * On error, FAMNextEvent and FAMPendingEvent will return -1 (and the global
! 289: * FAMErrno will be set to the value of the error).
! 290: *****************************************************************************/
! 291:
! 292: int FAMNextEvent(FAMConnection *fc, FAMEvent *fe);
! 293: int FAMPending(FAMConnection* fc);
! 294:
! 295:
! 296:
! 297:
! 298: /*****************************************************************************
! 299: * FAMDebugLevel
! 300: *
! 301: * This doesn't do anything.
! 302: *
! 303: *****************************************************************************/
! 304:
! 305: #define FAM_DEBUG_OFF 0
! 306: #define FAM_DEBUG_ON 1
! 307: #define FAM_DEBUG_VERBOSE 2
! 308:
! 309: int FAMDebugLevel(FAMConnection *fc, int debugLevel);
! 310:
! 311: #ifdef __cplusplus
! 312: }
! 313: #endif
! 314: #endif /* _FAM_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to fam.h CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [Development] / fam / include