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.. note:: 51 For FreeBSD path could sometimes be `NULL` due to a kernel bug. 52 53 .. _Reference: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=197695 54 55.. c:enum:: uv_fs_event 56 57 Event types that :c:type:`uv_fs_event_t` handles monitor. 58 59 :: 60 61 enum uv_fs_event { 62 UV_RENAME = 1, 63 UV_CHANGE = 2 64 }; 65 66.. c:enum:: uv_fs_event_flags 67 68 Flags that can be passed to :c:func:`uv_fs_event_start` to control its 69 behavior. 70 71 :: 72 73 enum uv_fs_event_flags { 74 /* 75 * By default, if the fs event watcher is given a directory name, we will 76 * watch for all events in that directory. This flags overrides this behavior 77 * and makes fs_event report only changes to the directory entry itself. This 78 * flag does not affect individual files watched. 79 * This flag is currently not implemented yet on any backend. 80 */ 81 UV_FS_EVENT_WATCH_ENTRY = 1, 82 /* 83 * By default uv_fs_event will try to use a kernel interface such as inotify 84 * or kqueue to detect events. This may not work on remote file systems such 85 * as NFS mounts. This flag makes fs_event fall back to calling stat() on a 86 * regular interval. 87 * This flag is currently not implemented yet on any backend. 88 */ 89 UV_FS_EVENT_STAT = 2, 90 /* 91 * By default, event watcher, when watching directory, is not registering 92 * (is ignoring) changes in its subdirectories. 93 * This flag will override this behaviour on platforms that support it. 94 */ 95 UV_FS_EVENT_RECURSIVE = 4 96 }; 97 98 99Public members 100^^^^^^^^^^^^^^ 101 102N/A 103 104.. seealso:: The :c:type:`uv_handle_t` members also apply. 105 106 107API 108--- 109 110.. c:function:: int uv_fs_event_init(uv_loop_t* loop, uv_fs_event_t* handle) 111 112 Initialize the handle. 113 114.. c:function:: int uv_fs_event_start(uv_fs_event_t* handle, uv_fs_event_cb cb, const char* path, unsigned int flags) 115 116 Start the handle with the given callback, which will watch the specified 117 `path` for changes. `flags` can be an ORed mask of :c:enum:`uv_fs_event_flags`. 118 119 .. note:: Currently the only supported flag is ``UV_FS_EVENT_RECURSIVE`` and 120 only on OSX and Windows. 121 .. note:: On macOS, events collected by the OS immediately before calling 122 ``uv_fs_event_start`` might be reported to the `uv_fs_event_cb` 123 callback. 124 125.. c:function:: int uv_fs_event_stop(uv_fs_event_t* handle) 126 127 Stop the handle, the callback will no longer be called. 128 129.. c:function:: int uv_fs_event_getpath(uv_fs_event_t* handle, char* buffer, size_t* size) 130 131 Get the path being monitored by the handle. The buffer must be preallocated 132 by the user. Returns 0 on success or an error code < 0 in case of failure. 133 On success, `buffer` will contain the path and `size` its length. If the buffer 134 is not big enough `UV_ENOBUFS` will be returned and `size` will be set to 135 the required size, including the null terminator. 136 137 .. versionchanged:: 1.3.0 the returned length no longer includes the terminating null byte, 138 and the buffer is not null terminated. 139 140 .. versionchanged:: 1.9.0 the returned length includes the terminating null 141 byte on `UV_ENOBUFS`, and the buffer is null terminated 142 on success. 143 144.. seealso:: The :c:type:`uv_handle_t` API functions also apply. 145
