|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. _fs_event:
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
:c:type:`uv_fs_event_t` --- FS Event handle
|
|
Packit |
b5b901 |
===========================================
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
FS Event handles allow the user to monitor a given path for changes, for example,
|
|
Packit |
b5b901 |
if the file was renamed or there was a generic change in it. This handle uses
|
|
Packit |
b5b901 |
the best backend for the job on each platform.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. note::
|
|
Packit |
b5b901 |
For AIX, the non default IBM bos.ahafs package has to be installed.
|
|
Packit |
b5b901 |
The AIX Event Infrastructure file system (ahafs) has some limitations:
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
- ahafs tracks monitoring per process and is not thread safe. A separate process
|
|
Packit |
b5b901 |
must be spawned for each monitor for the same event.
|
|
Packit |
b5b901 |
- Events for file modification (writing to a file) are not received if only the
|
|
Packit |
b5b901 |
containing folder is watched.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
See documentation_ for more details.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
The z/OS file system events monitoring infrastructure does not notify of file
|
|
Packit |
b5b901 |
creation/deletion within a directory that is being monitored.
|
|
Packit |
b5b901 |
See the `IBM Knowledge centre`_ for more details.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. _documentation: http://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/
|
|
Packit |
b5b901 |
.. _`IBM Knowledge centre`: https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r1.bpxb100/ioc.htm
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Data types
|
|
Packit |
b5b901 |
----------
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_fs_event_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
FS Event handle type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: void (*uv_fs_event_cb)(uv_fs_event_t* handle, const char* filename, int events, int status)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Callback passed to :c:func:`uv_fs_event_start` which will be called repeatedly
|
|
Packit |
b5b901 |
after the handle is started. If the handle was started with a directory the
|
|
Packit |
b5b901 |
`filename` parameter will be a relative path to a file contained in the directory.
|
|
Packit |
b5b901 |
The `events` parameter is an ORed mask of :c:type:`uv_fs_event` elements.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_fs_event
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Event types that :c:type:`uv_fs_event_t` handles monitor.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
::
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
enum uv_fs_event {
|
|
Packit |
b5b901 |
UV_RENAME = 1,
|
|
Packit |
b5b901 |
UV_CHANGE = 2
|
|
Packit |
b5b901 |
};
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_fs_event_flags
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Flags that can be passed to :c:func:`uv_fs_event_start` to control its
|
|
Packit |
b5b901 |
behavior.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
::
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
enum uv_fs_event_flags {
|
|
Packit |
b5b901 |
/*
|
|
Packit |
b5b901 |
* By default, if the fs event watcher is given a directory name, we will
|
|
Packit |
b5b901 |
* watch for all events in that directory. This flags overrides this behavior
|
|
Packit |
b5b901 |
* and makes fs_event report only changes to the directory entry itself. This
|
|
Packit |
b5b901 |
* flag does not affect individual files watched.
|
|
Packit |
b5b901 |
* This flag is currently not implemented yet on any backend.
|
|
Packit |
b5b901 |
*/
|
|
Packit |
b5b901 |
UV_FS_EVENT_WATCH_ENTRY = 1,
|
|
Packit |
b5b901 |
/*
|
|
Packit |
b5b901 |
* By default uv_fs_event will try to use a kernel interface such as inotify
|
|
Packit |
b5b901 |
* or kqueue to detect events. This may not work on remote file systems such
|
|
Packit |
b5b901 |
* as NFS mounts. This flag makes fs_event fall back to calling stat() on a
|
|
Packit |
b5b901 |
* regular interval.
|
|
Packit |
b5b901 |
* This flag is currently not implemented yet on any backend.
|
|
Packit |
b5b901 |
*/
|
|
Packit |
b5b901 |
UV_FS_EVENT_STAT = 2,
|
|
Packit |
b5b901 |
/*
|
|
Packit |
b5b901 |
* By default, event watcher, when watching directory, is not registering
|
|
Packit |
b5b901 |
* (is ignoring) changes in its subdirectories.
|
|
Packit |
b5b901 |
* This flag will override this behaviour on platforms that support it.
|
|
Packit |
b5b901 |
*/
|
|
Packit |
b5b901 |
UV_FS_EVENT_RECURSIVE = 4
|
|
Packit |
b5b901 |
};
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Public members
|
|
Packit |
b5b901 |
^^^^^^^^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
N/A
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. seealso:: The :c:type:`uv_handle_t` members also apply.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
API
|
|
Packit |
b5b901 |
---
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_fs_event_init(uv_loop_t* loop, uv_fs_event_t* handle)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Initialize the handle.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_fs_event_start(uv_fs_event_t* handle, uv_fs_event_cb cb, const char* path, unsigned int flags)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Start the handle with the given callback, which will watch the specified
|
|
Packit |
b5b901 |
`path` for changes. `flags` can be an ORed mask of :c:type:`uv_fs_event_flags`.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. note:: Currently the only supported flag is ``UV_FS_EVENT_RECURSIVE`` and
|
|
Packit |
b5b901 |
only on OSX and Windows.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_fs_event_stop(uv_fs_event_t* handle)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Stop the handle, the callback will no longer be called.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_fs_event_getpath(uv_fs_event_t* handle, char* buffer, size_t* size)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Get the path being monitored by the handle. The buffer must be preallocated
|
|
Packit |
b5b901 |
by the user. Returns 0 on success or an error code < 0 in case of failure.
|
|
Packit |
b5b901 |
On success, `buffer` will contain the path and `size` its length. If the buffer
|
|
Packit |
b5b901 |
is not big enough `UV_ENOBUFS` will be returned and `size` will be set to
|
|
Packit |
b5b901 |
the required size, including the null terminator.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. versionchanged:: 1.3.0 the returned length no longer includes the terminating null byte,
|
|
Packit |
b5b901 |
and the buffer is not null terminated.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. versionchanged:: 1.9.0 the returned length includes the terminating null
|
|
Packit |
b5b901 |
byte on `UV_ENOBUFS`, and the buffer is null terminated
|
|
Packit |
b5b901 |
on success.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. seealso:: The :c:type:`uv_handle_t` API functions also apply.
|