1 2.. _fs_event: 3 4:c:type:`uv_fs_event_t` --- FS Event handle 5=========================================== 6 7FS Event handles allow the user to monitor a given path for changes, for example, 8if the file was renamed or there was a generic change in it. This handle uses 9the best backend for the job on each platform. 10 11.. note:: 12 For AIX, the non default IBM bos.ahafs package has to be installed. 13 The AIX Event Infrastructure file system (ahafs) has some limitations: 14 15 - ahafs tracks monitoring per process and is not thread safe. A separate process 16 must be spawned for each monitor for the same event. 17 - Events for file modification (writing to a file) are not received if only the 18 containing folder is watched. 19 20 See documentation_ for more details. 21 22 The z/OS file system events monitoring infrastructure does not notify of file 23 creation/deletion within a directory that is being monitored. 24 See the `IBM Knowledge centre`_ for more details. 25 26 .. _documentation: https://developer.ibm.com/articles/au-aix_event_infrastructure/ 27 .. _`IBM Knowledge centre`: https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r1.bpxb100/ioc.htm 28 29 30 31 32Data types 33---------- 34 35.. c:type:: uv_fs_event_t 36 37 FS Event handle type. 38 39.. c:type:: void (*uv_fs_event_cb)(uv_fs_event_t* handle, const char* filename, int events, int status) 40 41 Callback passed to :c:func:`uv_fs_event_start` which will be called repeatedly 42 after the handle is started. 43 44 If the handle was started with a directory the `filename` parameter will 45 be a relative path to a file contained in the directory, or `NULL` if the 46 file name cannot be determined. 47 48 The `events` parameter is an ORed mask of :c:enum:`uv_fs_event` elements. 49 50.. c:enum:: uv_fs_event 51 52 Event types that :c:type:`uv_fs_event_t` handles monitor. 53 54 :: 55 56 enum uv_fs_event { 57 UV_RENAME = 1, 58 UV_CHANGE = 2 59 }; 60 61.. c:enum:: uv_fs_event_flags 62 63 Flags that can be passed to :c:func:`uv_fs_event_start` to control its 64 behavior. 65 66 :: 67 68 enum uv_fs_event_flags { 69 /* 70 * By default, if the fs event watcher is given a directory name, we will 71 * watch for all events in that directory. This flags overrides this behavior 72 * and makes fs_event report only changes to the directory entry itself. This 73 * flag does not affect individual files watched. 74 * This flag is currently not implemented yet on any backend. 75 */ 76 UV_FS_EVENT_WATCH_ENTRY = 1, 77 /* 78 * By default uv_fs_event will try to use a kernel interface such as inotify 79 * or kqueue to detect events. This may not work on remote file systems such 80 * as NFS mounts. This flag makes fs_event fall back to calling stat() on a 81 * regular interval. 82 * This flag is currently not implemented yet on any backend. 83 */ 84 UV_FS_EVENT_STAT = 2, 85 /* 86 * By default, event watcher, when watching directory, is not registering 87 * (is ignoring) changes in its subdirectories. 88 * This flag will override this behaviour on platforms that support it. 89 */ 90 UV_FS_EVENT_RECURSIVE = 4 91 }; 92 93 94Public members 95^^^^^^^^^^^^^^ 96 97N/A 98 99.. seealso:: The :c:type:`uv_handle_t` members also apply. 100 101 102API 103--- 104 105.. c:function:: int uv_fs_event_init(uv_loop_t* loop, uv_fs_event_t* handle) 106 107 Initialize the handle. 108 109.. c:function:: int uv_fs_event_start(uv_fs_event_t* handle, uv_fs_event_cb cb, const char* path, unsigned int flags) 110 111 Start the handle with the given callback, which will watch the specified 112 `path` for changes. `flags` can be an ORed mask of :c:enum:`uv_fs_event_flags`. 113 114 .. note:: Currently the only supported flag is ``UV_FS_EVENT_RECURSIVE`` and 115 only on OSX and Windows. 116 .. note:: On macOS, events collected by the OS immediately before calling 117 ``uv_fs_event_start`` might be reported to the `uv_fs_event_cb` 118 callback. 119 120.. c:function:: int uv_fs_event_stop(uv_fs_event_t* handle) 121 122 Stop the handle, the callback will no longer be called. 123 124.. c:function:: int uv_fs_event_getpath(uv_fs_event_t* handle, char* buffer, size_t* size) 125 126 Get the path being monitored by the handle. The buffer must be preallocated 127 by the user. Returns 0 on success or an error code < 0 in case of failure. 128 On success, `buffer` will contain the path and `size` its length. If the buffer 129 is not big enough `UV_ENOBUFS` will be returned and `size` will be set to 130 the required size, including the null terminator. 131 132 .. versionchanged:: 1.3.0 the returned length no longer includes the terminating null byte, 133 and the buffer is not null terminated. 134 135 .. versionchanged:: 1.9.0 the returned length includes the terminating null 136 byte on `UV_ENOBUFS`, and the buffer is null terminated 137 on success. 138 139.. seealso:: The :c:type:`uv_handle_t` API functions also apply. 140
