Previous example wouldn't run unless `std/posix` was imported and it
wasn't mentioned anywhere in the docs.
Other changes in the example:
- replaced magic number with constant `MaxWatches` .
- changed seq buffer to array, because length is already constant +
pointer is a bit nicer: `addr seq[0]` vs `addr arr`
- added example for getting a `cstring` name value from `InotifyEvent`
struct with explicit cast.
- added a bit more description to `inotify_init1` (copied from `man
inotify(7)`)
---------
Co-authored-by: ringabout <43030857+ringabout@users.noreply.github.com>
client code since Linux `inotify` is much like Linux `getdents64`.
Expanding on "almost always"..The only time that this `iterator` logic
is ***not*** needed on the output of a `read` from inotify fd's is when
one passes a length to `read` *guaranteed* to only pass one event struct
in the buffer. That unusual circumstance requires (at least!) knowing
the length of the delivered filename before an event occurs, and the
filename itself is optional for some event types.
It is *far* more common to not know lengths in advance which means one
passes a buffer big enough for at least one maximum length directory
entry (256 bytes) which is then also big enough for *many* "typical"
length entries and therefore many events. In such more common scenarios
this iterator logic is definitely needed.
Further, not using this logic, yet treating the return from read as "the
whole answer" can test ok on "thin" event streams (e.g. 1 event per ms),
hiding a latent bug of processing only the first event.
