From cabe03d8fe6e4579c93527a694541f436e437089 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Wed, 16 Dec 2015 10:36:00 +1000 Subject: [PATCH] Document that the fd should be drained before libevdev_set_fd 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 Acked-by: Benjamin Tissoires Acked-by: David Herrmann --- 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.34.1