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