Mercurial

comparison third_party/libuv/docs/src/fs_event.rst @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
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.