f11/sdk/lib/fdio/watcher.h.md

# \<lib/fdio/watcher.h\> in fdio

[Header source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/watcher.h)

## WATCH_EVENT_ADD_FILE macro {:#WATCH_EVENT_ADD_FILE}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/watcher.h#19)

<pre class="devsite-disable-click-to-copy">
<span class="kwd">#define</span> <span class="lit">WATCH_EVENT_ADD_FILE</span> 1
</pre>

This event occurs when a file is added or removed, including (for `fdio_watch_directory()`) files
that already exist.

## WATCH_EVENT_REMOVE_FILE macro {:#WATCH_EVENT_REMOVE_FILE}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/watcher.h#20)

<pre class="devsite-disable-click-to-copy">
<span class="kwd">#define</span> <span class="lit">WATCH_EVENT_REMOVE_FILE</span> 2
</pre>


## WATCH_EVENT_WAITING macro {:#WATCH_EVENT_WAITING}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/watcher.h#24)

<pre class="devsite-disable-click-to-copy">
<span class="kwd">#define</span> <span class="lit">WATCH_EVENT_WAITING</span> 3
</pre>

This event occurs, once, when `fdio_watch_directory()` runs out of existing files and has to
start waiting for new files to be added.

## watchdir_func_t typedef {:#watchdir_func_t}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/watcher.h#14)

<pre class="devsite-disable-click-to-copy">
<span class="kwd">typedef</span> <span class="typ">zx_status_t (*)(int, int, const char *, void *)</span> <span class="typ">watchdir_func_t</span>;
</pre>


## fdio_watch_directory(…) {:#fdio_watch_directory}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/watcher.h#38)

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_watch_directory</b>(<span class="typ">int</span> dirfd,
                                 <span class="typ">watchdir_func_t</span> cb,
                                 <span class="typ">zx_time_t</span> deadline,
                                 <span class="typ">void *</span> cookie);
</pre>

Call the provided callback (cb) for each file in directory and each time a new file is added to
the directory.

If the callback returns a status other than `ZX_OK`, watching stops and the callback's status is
returned to the caller of fdio_watch_directory.

If the deadline expires, `ZX_ERR_TIMED_OUT` is returned to the caller.  A deadline of
`ZX_TIME_INFINITE` will never expire.

The callback may use `ZX_ERR_STOP` as a way to signal to the caller that it wants to stop because
it found what it was looking for, etc -- since this error code is not returned by syscalls or
public APIs, the callback does not need to worry about it turning up normally.