|
160
|
1
|
|
|
2 .. _fs_event:
|
|
|
3
|
|
|
4 :c:type:`uv_fs_event_t` --- FS Event handle
|
|
|
5 ===========================================
|
|
|
6
|
|
|
7 FS Event handles allow the user to monitor a given path for changes, for example,
|
|
|
8 if the file was renamed or there was a generic change in it. This handle uses
|
|
|
9 the 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
|
|
|
32 Data 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
|
|
|
99 Public members
|
|
|
100 ^^^^^^^^^^^^^^
|
|
|
101
|
|
|
102 N/A
|
|
|
103
|
|
|
104 .. seealso:: The :c:type:`uv_handle_t` members also apply.
|
|
|
105
|
|
|
106
|
|
|
107 API
|
|
|
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.
|
