[PATCH libevdev] Document that the fd should be drained before libevdev_set_fd

[Peter Hutterer]

This is the caller's responsibility, for two reasons:
* we don't know if O_NONBLOCK is set, so draining the fd isn't a simple matter
  of read() until EAGAIN. A select() + read() could work around this of
  course.
* for stateless information, keys and relative data, it is not a problem when
  there are events waiting on the fd already, they are processed correctly,
  albeit with a delay.

So punt this decision to the caller, they openend the fd, they know if they
care about delayed events, they can drain the fd before handing it to us.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 libevdev/libevdev.h | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h
index eae8e7b..27e36d8 100644
--- a/libevdev/libevdev.h
+++ b/libevdev/libevdev.h
@@ -78,7 +78,8 @@ extern "C" {
  *
  * libevdev does not handle the file descriptors directly, it merely uses
  * them. The caller is responsible for opening the file descriptors, setting
- * them to O_NONBLOCK and handling permissions.
+ * them to O_NONBLOCK and handling permissions. A caller should drain any
+ * events pending on the file descriptor before passing it to libevdev.
  *
  * Where does libevdev sit?
  * ========================
@@ -974,6 +975,15 @@ int libevdev_grab(struct libevdev *dev, enum libevdev_grab_mode grab);
  * you need to change the fd after closing and re-opening the same device, use
  * libevdev_change_fd().
  *
+ * A caller should ensure that any events currently pending on the fd are
+ * drained before the file descriptor is passed to libevdev for
+ * initialization. Due to how the kernel's ioctl handling works, the initial
+ * device state will reflect the current device state *after* applying all
+ * events currently pending on the fd. Thus, if the fd is not drained, the
+ * state visible to the caller will be inconsistent with the events
+ * immediately available on the device. This does not affect state-less
+ * events like EV_REL.
+ *
  * Unless otherwise specified, libevdev function behavior is undefined until
  * a successfull call to libevdev_set_fd().
  *
-- 
2.5.0