xref: /libuv/docs/src/fs_event.rst (revision 5cc71755)
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