2 * Copyright © 2013 Red Hat, Inc.
4 * Permission to use, copy, modify, distribute, and sell this software and its
5 * documentation for any purpose is hereby granted without fee, provided that
6 * the above copyright notice appear in all copies and that both that copyright
7 * notice and this permission notice appear in supporting documentation, and
8 * that the name of the copyright holders not be used in advertising or
9 * publicity pertaining to distribution of the software without specific,
10 * written prior permission. The copyright holders make no representations
11 * about the suitability of this software for any purpose. It is provided "as
12 * is" without express or implied warranty.
14 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
15 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
16 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
17 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
18 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
19 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
26 #include <linux/input.h>
32 * **libevdev** is a library for handling evdev kernel devices. It abstracts
33 * the ioctls through type-safe interfaces and provides functions to change
34 * the appearance of the device.
36 * Development of libevdev is discussed on
37 * [input-tools@lists.freedesktop.org](http://lists.freedesktop.org/mailman/listinfo/input-tools)
38 * Please submit patches, questions or general comments there.
40 * Handling events and SYN_DROPPED
41 * ===============================
43 * libevdev provides an interface for handling events, including most notably
44 * SYN_DROPPED events. SYN_DROPPED events are sent by the kernel when the
45 * process does not read events fast enough and the kernel is forced to drop
46 * some events. This causes the device to get out of sync with the process'
47 * view of it. libevdev handles this by telling the caller that a SYN_DROPPED
48 * has been received and that the state of the device is different to what is
49 * to be expected. It then provides the delta between the previous state and
50 * the actual state of the device as a set of events. See
51 * libevdev_next_event() for more information.
56 * libevdev is signal-safe for the majority of its operations. Check the API
57 * documentation to make sure, unless explicitly stated a call is <b>not</b>
63 * libevdev does not attempt duplicate detection. Initializing two libevdev
64 * devices for the same fd is valid and behaves the same as for two different
67 * libevdev does not handle the file descriptors directly, it merely uses
68 * them. The caller is responsible for opening the file descriptors, setting
69 * them to O_NONBLOCK and handling permissions.
71 * Where does libevdev sit?
72 * ========================
74 * libevdev is essentially a `read(2)` on steroids for `/dev/input/eventX
75 * devices. It sits below the process that handles input events, in between
76 * the kernel and that process. In the simplest case, e.g. an evtest-like tool
77 * the stack would look like this:
79 * kernel → libevdev → evtest
81 * For X.Org input modules, the stack would look like this:
83 * kernel → libevdev → xf86-input-evdev → X server → X client
85 * For Weston/Wayland, the stack would look like this:
87 * kernel → libevdev → Weston → Wayland client
89 * libevdev does **not** have knowledge of X clients or Wayland clients, it is
90 * too low in the stack.
94 * Below is a simple example that shows how libevdev could be used. This example
95 * opens a device, checks for relative axes and a left mouse button and if it
96 * finds them monitors the device to print the event.
99 * struct libevdev *dev = NULL;
103 * fd = open("/dev/input/event0", O_RDONLY|O_NONBLOCK);
104 * rc = libevdev_new_from_fd(fd, &dev);
106 * fprintf(stderr, "Failed to init libevdev (%s)\n", strerror(-rc));
109 * printf("Input device name: \"%s\"\n", libevdev_get_name(dev));
110 * printf("Input device ID: bus %#x vendor %#x product %#x\n",
111 * libevdev_get_bustype(dev),
112 * libevdev_get_vendor_id(dev),
113 * libevdev_get_product_id(dev));
114 * if (!libevdev_has_event_type(dev, EV_REL) ||
115 * !libevdev_has_event_code(dev, EV_KEY, BTN_LEFT)) {
116 * printf("This device does not look like a mouse\n");
121 * struct input_event ev;
122 * rc = libevdev_next_event(dev, LIBEVDEV_READ_NORMAL, &ev);
124 * printf("Event: %s %s %d\n",
125 * libevdev_get_event_type_name(ev.type),
126 * libevdev_get_event_code_name(ev.type, ev.code),
128 * } while (rc == 1 || rc == 0 || rc == -EAGAIN);
131 * A more complete example is available with the libevdev-events tool here:
132 * http://cgit.freedesktop.org/libevdev/tree/tools/libevdev-events.c
134 * libevdev internal test suite
135 * ============================
137 * libevdev's internal test suite uses the
138 * [Check unit testing framework](http://check.sourceforge.net/). Tests are
139 * divided into test suites and test cases. Most tests create a uinput device,
140 * so you'll need to run as root.
142 * To run a specific suite only:
144 * export CK_RUN_SUITE="suite name"
146 * To run a specific test case only:
148 * export CK_RUN_TEST="test case name"
150 * To get a list of all suites or tests:
152 * git grep "suite_create"
153 * git grep "tcase_create"
155 * By default, check forks, making debugging harder. Run gdb as below to avoid
158 * sudo CK_FORK=no CK_RUN_TEST="test case name" gdb ./test/test-libevdev
160 * A special target `make gcov-report.txt` exists that runs gcov and leaves a
161 * `libevdev.c.gcov` file. Check that for test coverage.
163 * `make check` is hooked up to run the test and gcov (again, needs root).
165 * The test suite creates a lot of devices, very quickly. Add the following
166 * xorg.conf.d snippet to avoid the devices being added as X devices (at the
167 * time of writing, mutter can't handle these devices and exits after getting
168 * a BadDevice error).
170 * $ cat /etc/X11/xorg.conf.d/99-ignore-libevdev-devices.conf
171 * Section "InputClass"
172 * Identifier "Ignore libevdev test devices"
173 * MatchProduct "libevdev test device"
174 * Option "Ignore" "on"
177 * License information
178 * ===================
179 * libevdev is licensed under the
180 * [X11 license](http://cgit.freedesktop.org/libevdev/tree/COPYING).
184 * Please report bugs in the freedesktop.org bugzilla under the libevdev product:
185 * https://bugs.freedesktop.org/enter_bug.cgi?product=libevdev
189 * @defgroup init Initialization and setup
191 * Initialization, initial setup and file descriptor handling.
192 * These functions are the main entry points for users of libevdev, usually a
193 * caller will use this series of calls:
196 * struct libevdev *dev;
199 * dev = libevdev_new();
203 * err = libevdev_set_fd(dev, fd);
205 * printf("Failed (errno %d): %s\n", -err, strerror(-err));
207 * libevdev_free(dev);
210 * libevdev_set_fd() is the central call and initializes the internal structs
211 * for the device at the given fd. libevdev functions will fail if called
212 * before libevdev_set_fd() unless documented otherwise.
216 * @defgroup bits Querying device capabilities
218 * Abstraction functions to handle device capabilities, specificially
219 * device propeties such as the name of the device and the bits
220 * representing the events suppported by this device.
222 * The logical state returned may lag behind the physical state of the device.
223 * libevdev queries the device state on libevdev_set_fd() and then relies on
224 * the caller to parse events through libevdev_next_fd(). If a caller does not
225 * use libevdev_next_fd(), libevdev will not update the internal state of the
226 * device and thus returns outdated values.
230 * @defgroup mt Multi-touch related functions
231 * Functions for querying multi-touch-related capabilities. MT devices
232 * following the kernel protocol B (using ABS_MT_SLOT) provide multiple touch
233 * points through so-called slots on the same axis. The slots are enumerated,
234 * a client reading from the device will first get an ABS_MT_SLOT event, then
235 * the values of axes changed in this slot. Multiple slots may be provided in
236 * before an EV_SYN event.
238 * As with @ref bits, the logical state of the device as seen by the library
239 * depends on the caller using libevdev_next_event().
243 * @defgroup kernel Modifying the appearance or capabilities of the device
245 * Modifying the set of events reported by this device. By default, the
246 * libevdev device mirrors the kernel device, enabling only those bits
247 * exported by the kernel. This set of functions enable or disable bits as
248 * seen from the caller.
250 * Enabling an event type or code does not affect event reporting - a
251 * software-enabled event will not be generated by the physical hardware.
252 * Disabling an event will prevent libevdev from routing such events to the
253 * caller. Enabling and disabling event types and codes is at the library
254 * level and thus only affects the caller.
256 * If an event type or code is enabled at kernel-level, future users of this
257 * device will see this event enabled. Currently there is no option of
258 * disabling an event type or code at kernel-level.
262 * @defgroup misc Miscellaneous helper functions
264 * Functions for printing or querying event ranges. The list of names is
265 * compiled into libevdev and will not change when the kernel changes. Adding
266 * or removing names requires a re-compilation of libevdev. Likewise, the max
267 * for each event type is compiled in and does not check the underlying
272 * @defgroup events Event handling
274 * Functions to handle events and fetch the current state of the event. Generally,
275 * libevdev updates its internal state as the event is processed and forwarded
276 * to the caller. Thus, the libevdev state of the device should always be identical
277 * to the caller's state. It may however lag behind the actual state of the device.
283 * Opaque struct representing an evdev device.
287 enum libevdev_read_flag {
288 LIBEVDEV_READ_SYNC = 1, /**< Process data in sync mode */
289 LIBEVDEV_READ_NORMAL = 2, /**< Process data in normal mode */
290 LIBEVDEV_FORCE_SYNC = 4, /**< Pretend the next event is a SYN_DROPPED. There is
291 no reason to ever use this except for
292 automated tests, so don't. */
293 LIBEVDEV_READ_BLOCKING = 8, /**< The fd is not in O_NONBLOCK and a read may block */
299 * Initialize a new libevdev device. This function only allocates the
300 * required memory and initializes the struct to sane default values.
301 * To actually hook up the device to a kernel device, use
304 * Memory allocated through libevdev_new() must be released by the
305 * caller with libevdev_free().
307 * @see libevdev_set_fd
310 struct libevdev* libevdev_new(void);
315 * Initialize a new libevdev device from the given fd.
317 * This is a shortcut for
321 * struct libevdev *dev = libevdev_new();
322 * err = libevdev_set_fd(dev, fd);
325 * @param fd A file descriptor to the device in O_RDWR or O_RDONLY mode.
326 * @param[out] dev The newly initialized evdev device.
328 * @return On success, zero is returned and dev is set to the newly
329 * allocated struct. On failure, a negative errno is returned and the value
330 * of dev is undefined.
334 int libevdev_new_from_fd(int fd, struct libevdev **dev);
339 * Clean up and free the libevdev struct. After completion, the <code>struct
340 * libevdev</code> is invalid and must not be used.
342 * @param dev The evdev device
344 * @note This function may be called before libevdev_set_fd().
346 void libevdev_free(struct libevdev *dev);
349 * Logging function called by library-internal logging.
350 * This function is expected to treat it's input like printf would.
352 * @param format printf-style format string
353 * @param args List of arguments
355 * @see libevdev_set_log_handler
357 typedef void (*libevdev_log_func_t)(const char *format, va_list args);
360 * Set a printf-style logging handler for library-internal logging. The default
361 * logging function is a noop.
363 * @param dev The evdev device
364 * @param logfunc The logging function for this device. If NULL, the current
365 * logging function is unset.
367 * @note This function may be called before libevdev_set_fd().
369 void libevdev_set_log_handler(struct libevdev *dev, libevdev_log_func_t logfunc);
372 enum libevdev_grab_mode {
378 * Grab or ungrab the device through a kernel EVIOCGRAB. This prevents other
379 * clients (including kernel-internal ones such as rfkill) from receiving
380 * events from this device.
382 * This is generally a bad idea. Don't do this.
384 * Grabbing an already grabbed device, or ungrabbing an ungrabbed device is
385 * a noop and always succeeds.
387 * @param dev The evdev device, already initialized with libevdev_set_fd()
388 * @param grab If true, grab the device. Otherwise ungrab the device.
390 * @return 0 if the device was successfull grabbed or ungrabbed, or a
391 * negative errno in case of failure.
393 int libevdev_grab(struct libevdev *dev, enum libevdev_grab_mode grab);
398 * Set the fd for this struct and initialize internal data.
399 * The fd must be in O_RDONLY or O_RDWR mode.
401 * This function may only be called once per device. If the device changed and
402 * you need to re-read a device, use libevdev_free() and libevdev_new(). If
403 * you need to change the fd after closing and re-opening the same device, use
404 * libevdev_change_fd().
406 * Unless otherwise specified, libevdev function behavior is undefined until
407 * a successfull call to libevdev_set_fd().
409 * @param dev The evdev device
410 * @param fd The file descriptor for the device
412 * @return 0 on success, or a negative error code on failure
414 * @see libevdev_change_fd
418 int libevdev_set_fd(struct libevdev* dev, int fd);
423 * Change the fd for this device, without re-reading the actual device. If the fd
424 * changes after initializing the device, for example after a VT-switch in the
425 * X.org X server, this function updates the internal fd to the newly opened.
426 * No check is made that new fd points to the same device. If the device has
427 * changed, libevdev's behavior is undefined.
429 * The fd may be open in O_RDONLY or O_RDWR.
431 * It is an error to call this function before calling libevdev_set_fd().
433 * @param dev The evdev device, already initialized with libevdev_set_fd()
434 * @param fd The new fd
436 * @return 0 on success, or -1 on failure.
438 * @see libevdev_set_fd
440 int libevdev_change_fd(struct libevdev* dev, int fd);
443 * @param dev The evdev device
445 * @return The previously set fd, or -1 if none had been set previously.
446 * @note This function may be called before libevdev_set_fd().
448 int libevdev_get_fd(const struct libevdev* dev);
453 * Get the next event from the device. This function operates in two different
454 * modes: normal mode or sync mode.
456 * In normal mode, this function returns 0 and returns the event in the
457 * parameter ev. If no events are available at this time, it returns -EAGAIN
458 * and ev is undefined.
460 * If a SYN_DROPPED is read from the device, this function returns 1. The
461 * caller should now call this function with the LIBEVDEV_READ_SYNC flag set,
462 * to get the set of events that make up the device state delta. This function
463 * returns 1 for each event part of that delta, until it returns -EAGAIN once
464 * all events have been synced.
466 * If a device needs to be synced by the caller but the caller does not call
467 * with the LIBEVDEV_READ_SYNC flag set, all events from the diff are dropped
468 * and event processing continues as normal.
470 * @param dev The evdev device, already initialized with libevdev_set_fd()
471 * @param flags Set of flags to determine behaviour. If LIBEVDEV_READ_NORMAL
472 * is set, the next event is read in normal mode. If LIBEVDEV_READ_SYNC is
473 * set, the next event is read in sync mode.
474 * @param ev On success, set to the current event.
475 * @return On failure, a negative errno is returned.
476 * @retval 0 One or more events where read of the device
477 * @retval -EAGAIN No events are currently available on the device
478 * @retval 1 A SYN_DROPPED event was received, or a synced event was
481 * @note This function is signal-safe.
483 int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_event *ev);
488 * Check if there are events waiting for us. This does not read an event off
489 * the fd and may not access the fd at all. If there are events queued
490 * internally this function will return non-zero. If the internal queue is empty,
491 * this function will poll the file descriptor for data.
493 * This is a convenience function for simple processes, most complex programs
494 * are expected to use select(2) or poll(2) on the file descriptor. The kernel
495 * guarantees that if data is available, it is a multiple of sizeof(struct
496 * input_event), and thus calling libevdev_next_event() when select(2) or
497 * poll(2) return is safe. You do not need libevdev_has_event_pending() if
498 * you're using select(2) or poll(2).
500 * @param dev The evdev device, already initialized with libevdev_set_fd()
501 * @return On failure, a negative errno is returned.
502 * @retval 0 No event is currently available
503 * @retval 1 One or more events are available on the fd
505 * @note This function is signal-safe.
507 int libevdev_has_event_pending(struct libevdev *dev);
512 * @param dev The evdev device, already initialized with libevdev_set_fd()
514 * @return The device name as read off the kernel device. The name is never
515 * NULL but it may be the empty string.
517 * @note This function is signal-safe.
519 const char* libevdev_get_name(const struct libevdev *dev);
524 * @param dev The evdev device
525 * @param name The new, non-NULL, name to assign to this device.
527 * @note This function may be called before libevdev_set_fd(). A call to
528 * libevdev_set_fd() will overwrite any previously set value.
530 void libevdev_set_name(struct libevdev *dev, const char *name);
535 * Virtual devices such as uinput devices have no phys location.
537 * @param dev The evdev device, already initialized with libevdev_set_fd()
539 * @return The physical location of this device, or NULL if there is none
541 * @note This function is signal safe.
543 const char * libevdev_get_phys(const struct libevdev *dev);
548 * @param dev The evdev device
549 * @param phys The new, non-NULL, phys to assign to this device.
551 * @note This function may be called before libevdev_set_fd(). A call to
552 * libevdev_set_fd() will overwrite any previously set value.
554 void libevdev_set_phys(struct libevdev *dev, const char *phys);
559 * @param dev The evdev device, already initialized with libevdev_set_fd()
561 * @return The unique identifier for this device, or NULL if there is none
563 * @note This function is signal safe.
565 const char * libevdev_get_uniq(const struct libevdev *dev);
570 * @param dev The evdev device
571 * @param uniq The new, non-NULL, uniq to assign to this device.
573 * @note This function may be called before libevdev_set_fd(). A call to
574 * libevdev_set_fd() will overwrite any previously set value.
576 void libevdev_set_uniq(struct libevdev *dev, const char *uniq);
581 * @param dev The evdev device, already initialized with libevdev_set_fd()
583 * @return The device's product ID
585 * @note This function is signal-safe.
587 int libevdev_get_id_product(const struct libevdev *dev);
592 * @param dev The evdev device
593 * @param product_id The product ID to assign to this device
595 * @note This function may be called before libevdev_set_fd(). A call to
596 * libevdev_set_fd() will overwrite any previously set value.
598 void libevdev_set_id_product(struct libevdev *dev, int product_id);
603 * @param dev The evdev device, already initialized with libevdev_set_fd()
605 * @return The device's vendor ID
607 * @note This function is signal-safe.
609 int libevdev_get_id_vendor(const struct libevdev *dev);
614 * @param dev The evdev device
615 * @param vendor_id The vendor ID to assign to this device
617 * @note This function may be called before libevdev_set_fd(). A call to
618 * libevdev_set_fd() will overwrite any previously set value.
620 void libevdev_set_id_vendor(struct libevdev *dev, int vendor_id);
625 * @param dev The evdev device, already initialized with libevdev_set_fd()
627 * @return The device's bus type
629 * @note This function is signal-safe.
631 int libevdev_get_id_bustype(const struct libevdev *dev);
636 * @param dev The evdev device
637 * @param bustype The bustype to assign to this device
639 * @note This function may be called before libevdev_set_fd(). A call to
640 * libevdev_set_fd() will overwrite any previously set value.
642 void libevdev_set_id_bustype(struct libevdev *dev, int bustype);
647 * @param dev The evdev device, already initialized with libevdev_set_fd()
649 * @return The device's firmware version
651 * @note This function is signal-safe.
653 int libevdev_get_id_version(const struct libevdev *dev);
658 * @param dev The evdev device
659 * @param version The version to assign to this device
661 * @note This function may be called before libevdev_set_fd(). A call to
662 * libevdev_set_fd() will overwrite any previously set value.
664 void libevdev_set_id_version(struct libevdev *dev, int version);
669 * @param dev The evdev device, already initialized with libevdev_set_fd()
671 * @return The driver version for this device
673 * @note This function is signal-safe.
675 int libevdev_get_driver_version(const struct libevdev *dev);
680 * @param dev The evdev device, already initialized with libevdev_set_fd()
681 * @param prop The input property to query for, one of INPUT_PROP_...
683 * @return 1 if the device provides this input property, or 0 otherwise.
685 * @note This function is signal-safe
687 int libevdev_has_property(const struct libevdev *dev, unsigned int prop);
692 * @param dev The evdev device
693 * @param prop The input property to enable, one of INPUT_PROP_...
695 * @return 0 on success or -1 on failure
697 * @note This function may be called before libevdev_set_fd(). A call to
698 * libevdev_set_fd() will overwrite any previously set value.
700 int libevdev_enable_property(struct libevdev *dev, unsigned int prop);
705 * @param dev The evdev device, already initialized with libevdev_set_fd()
706 * @param type The event type to query for, one of EV_SYN, EV_REL, etc.
708 * @return 1 if the device supports this event type, or 0 otherwise.
710 * @note This function is signal-safe.
712 int libevdev_has_event_type(const struct libevdev *dev, unsigned int type);
717 * @param dev The evdev device, already initialized with libevdev_set_fd()
718 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.)
719 * @param code The event code to query for, one of ABS_X, REL_X, etc.
721 * @return 1 if the device supports this event type and code, or 0 otherwise.
723 * @note This function is signal-safe.
725 int libevdev_has_event_code(const struct libevdev *dev, unsigned int type, unsigned int code);
730 * Get the minimum axis value for the given axis, as advertised by the kernel.
732 * @param dev The evdev device, already initialized with libevdev_set_fd()
733 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
735 * @return axis minimum for the given axis or 0 if the axis is invalid
737 int libevdev_get_abs_minimum(const struct libevdev *dev, unsigned int code);
741 * Get the maximum axis value for the given axis, as advertised by the kernel.
743 * @param dev The evdev device, already initialized with libevdev_set_fd()
744 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
746 * @return axis maximum for the given axis or 0 if the axis is invalid
748 int libevdev_get_abs_maximum(const struct libevdev *dev, unsigned int code);
752 * Get the axis fuzz for the given axis, as advertised by the kernel.
754 * @param dev The evdev device, already initialized with libevdev_set_fd()
755 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
757 * @return axis fuzz for the given axis or 0 if the axis is invalid
759 int libevdev_get_abs_fuzz(const struct libevdev *dev, unsigned int code);
763 * Get the axis flat for the given axis, as advertised by the kernel.
765 * @param dev The evdev device, already initialized with libevdev_set_fd()
766 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
768 * @return axis flat for the given axis or 0 if the axis is invalid
770 int libevdev_get_abs_flat(const struct libevdev *dev, unsigned int code);
774 * Get the axis resolution for the given axis, as advertised by the kernel.
776 * @param dev The evdev device, already initialized with libevdev_set_fd()
777 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
779 * @return axis resolution for the given axis or 0 if the axis is invalid
781 int libevdev_get_abs_resolution(const struct libevdev *dev, unsigned int code);
786 * Get the axis info for the given axis, as advertised by the kernel.
788 * @param dev The evdev device, already initialized with libevdev_set_fd()
789 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
791 * @return The input_absinfo for the given code, or NULL if the device does
792 * not support this event code.
794 const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, unsigned int code);
799 * Behaviour of this function is undefined if the device does not provide
802 * If the device supports ABS_MT_SLOT, the value returned for any ABS_MT_*
803 * event code is the value of the currently active slot. You should use
804 * libevdev_get_slot_value() instead.
806 * @param dev The evdev device, already initialized with libevdev_set_fd()
807 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.)
808 * @param code The event code to query for, one of ABS_X, REL_X, etc.
810 * @return The current value of the event.
812 * @note This function is signal-safe.
813 * @note The value for ABS_MT_ events is undefined, use
814 * libevdev_get_slot_value() instead
816 * @see libevdev_get_slot_value
818 int libevdev_get_event_value(const struct libevdev *dev, unsigned int type, unsigned int code);
823 * Set the value for a given event type and code. This only makes sense for
824 * some event types, e.g. setting the value for EV_REL is pointless.
826 * This is a local modification only affecting only this representation of
827 * this device. A future call to libevdev_get_event_value() will return this
828 * value, unless the value was overwritten by an event.
830 * If the device supports ABS_MT_SLOT, the value set for any ABS_MT_*
831 * event code is the value of the currently active slot. You should use
832 * libevdev_set_slot_value() instead.
834 * @param dev The evdev device, already initialized with libevdev_set_fd()
835 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.)
836 * @param code The event code to set the value for, one of ABS_X, LED_NUML, etc.
837 * @param value The new value to set
839 * @return 0 on success, or -1 on failure.
840 * @retval -1 the device does not have the event type or code enabled, or the code is outside the
841 * allowed limits for the given type, or the type cannot be set.
843 * @see libevdev_set_slot_value
844 * @see libevdev_get_event_value
846 int libevdev_set_event_value(struct libevdev *dev, unsigned int type, unsigned int code, int value);
851 * Fetch the current value of the event type. This is a shortcut for
854 * if (libevdev_has_event_type(dev, t) && libevdev_has_event_code(dev, t, c))
855 * val = libevdev_get_event_value(dev, t, c);
858 * @param dev The evdev device, already initialized with libevdev_set_fd()
859 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.)
860 * @param code The event code to query for, one of ABS_X, REL_X, etc.
861 * @param[out] value The current value of this axis returned.
863 * @return If the device supports this event type and code, the return value is
864 * non-zero and value is set to the current value of this axis. Otherwise,
865 * zero is returned and value is unmodified.
867 * @note This function is signal-safe.
868 * @note The value for ABS_MT_ events is undefined, use
869 * libevdev_fetch_slot_value() instead
871 * @see libevdev_fetch_slot_value
873 int libevdev_fetch_event_value(const struct libevdev *dev, unsigned int type, unsigned int code, int *value);
878 * Return the current value of the code for the given slot.
880 * The return value is undefined for a slot exceeding the available slots on
881 * the device, for a code that is not in the permitted ABS_MT range or for a
882 * device that does not have slots.
884 * @param dev The evdev device, already initialized with libevdev_set_fd()
885 * @param slot The numerical slot number, must be smaller than the total number
886 * of slots on this device
887 * @param code The event code to query for, one of ABS_MT_POSITION_X, etc.
889 * @note This function is signal-safe.
890 * @note The value for events other than ABS_MT_ is undefined, use
891 * libevdev_fetch_value() instead
893 * @see libevdev_get_value
895 int libevdev_get_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code);
900 * Set the value for a given code for the given slot.
902 * This is a local modification only affecting only this representation of
903 * this device. A future call to libevdev_get_slot_value() will return this
904 * value, unless the value was overwritten by an event.
906 * This function does not set event values for axes outside the ABS_MT range,
907 * use libevdev_set_event_value() instead.
909 * @param dev The evdev device, already initialized with libevdev_set_fd()
910 * @param slot The numerical slot number, must be smaller than the total number
911 * of slots on this device
912 * @param code The event code to set the value for, one of ABS_MT_POSITION_X, etc.
913 * @param value The new value to set
915 * @return 0 on success, or -1 on failure.
916 * @retval -1 the device does not have the event code enabled, or the code is
917 * outside the allowed limits for multitouch events, or the slot number is outside
918 * the limits for this device, or the device does not support multitouch events.
920 * @see libevdev_set_event_value
921 * @see libevdev_get_slot_value
923 int libevdev_set_slot_value(struct libevdev *dev, unsigned int slot, unsigned int code, int value);
928 * Fetch the current value of the code for the given slot. This is a shortcut for
931 * if (libevdev_has_event_type(dev, EV_ABS) &&
932 * libevdev_has_event_code(dev, EV_ABS, c) &&
933 * slot < device->number_of_slots)
934 * val = libevdev_get_slot_value(dev, slot, c);
937 * @param dev The evdev device, already initialized with libevdev_set_fd()
938 * @param slot The numerical slot number, must be smaller than the total number
939 * of slots on this * device
940 * @param[out] value The current value of this axis returned.
942 * @param code The event code to query for, one of ABS_MT_POSITION_X, etc.
943 * @return If the device supports this event code, the return value is
944 * non-zero and value is set to the current value of this axis. Otherwise, or
945 * if the event code is not an ABS_MT_* event code, zero is returned and value
948 * @note This function is signal-safe.
950 int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code, int *value);
955 * Get the number of slots supported by this device.
957 * @param dev The evdev device, already initialized with libevdev_set_fd()
959 * @return The number of slots supported, or -1 if the device does not provide
962 * @note A device may provide ABS_MT_SLOT but a total number of 0 slots. Hence
963 * the return value of -1 for "device does not provide slots at all"
965 int libevdev_get_num_slots(const struct libevdev *dev);
970 * Get the currently active slot. This may differ from the value
971 * an ioctl may return at this time as events may have been read off the fd
972 * since changing the slot value but those events are still in the buffer
973 * waiting to be processed. The returned value is the value a caller would
974 * see if it were to process events manually one-by-one.
976 * @param dev The evdev device, already initialized with libevdev_set_fd()
978 * @return the currently active slot (logically)
980 int libevdev_get_current_slot(const struct libevdev *dev);
985 * Change the minimum for the given EV_ABS event code, if the code exists.
986 * This function has no effect if libevdev_has_event_code() returns false for
989 void libevdev_set_abs_minimum(struct libevdev *dev, unsigned int code, int min);
994 * Change the maximum for the given EV_ABS event code, if the code exists.
995 * This function has no effect if libevdev_has_event_code() returns false for
998 void libevdev_set_abs_maximum(struct libevdev *dev, unsigned int code, int max);
1003 * Change the fuzz for the given EV_ABS event code, if the code exists.
1004 * This function has no effect if libevdev_has_event_code() returns false for
1007 void libevdev_set_abs_fuzz(struct libevdev *dev, unsigned int code, int fuzz);
1012 * Change the flat for the given EV_ABS event code, if the code exists.
1013 * This function has no effect if libevdev_has_event_code() returns false for
1016 void libevdev_set_abs_flat(struct libevdev *dev, unsigned int code, int flat);
1021 * Change the resolution for the given EV_ABS event code, if the code exists.
1022 * This function has no effect if libevdev_has_event_code() returns false for
1025 void libevdev_set_abs_resolution(struct libevdev *dev, unsigned int code, int resolution);
1030 * Change the abs info for the given EV_ABS event code, if the code exists.
1031 * This function has no effect if libevdev_has_event_code() returns false for
1034 void libevdev_set_abs_info(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs);
1039 * Forcibly enable an event type on this device, even if the underlying
1040 * device does not support it. While this cannot make the device actually
1041 * report such events, it will now return true for libevdev_has_event_type().
1043 * This is a local modification only affecting only this representation of
1046 * @param dev The evdev device, already initialized with libevdev_set_fd()
1047 * @param type The event type to enable (EV_ABS, EV_KEY, ...)
1049 * @return 0 on success or -1 otherwise
1051 * @see libevdev_has_event_type
1053 int libevdev_enable_event_type(struct libevdev *dev, unsigned int type);
1058 * Forcibly disable an event type on this device, even if the underlying
1059 * device provides it. This effectively mutes the respective set of
1060 * events. libevdev will filter any events matching this type and none will
1061 * reach the caller. libevdev_has_event_type() will return false for this
1064 * In most cases, a caller likely only wants to disable a single code, not
1065 * the whole type. Use libevdev_disable_event_code() for that.
1067 * Disabling EV_SYN will not work. Don't shoot yourself in the foot.
1070 * This is a local modification only affecting only this representation of
1073 * @param dev The evdev device, already initialized with libevdev_set_fd()
1074 * @param type The event type to disable (EV_ABS, EV_KEY, ...)
1076 * @return 0 on success or -1 otherwise
1078 * @see libevdev_has_event_type
1079 * @see libevdev_disable_event_type
1081 int libevdev_disable_event_type(struct libevdev *dev, unsigned int type);
1086 * Forcibly enable an event type on this device, even if the underlying
1087 * device does not support it. While this cannot make the device actually
1088 * report such events, it will now return true for libevdev_has_event_code().
1090 * The last argument depends on the type and code:
1091 * - If type is EV_ABS, data must be a pointer to a struct input_absinfo
1092 * containing the data for this axis.
1093 * - For all other types, the argument must be NULL.
1095 * This function calls libevdev_enable_event_type() if necessary.
1097 * This is a local modification only affecting only this representation of
1100 * @param dev The evdev device, already initialized with libevdev_set_fd()
1101 * @param type The event type to enable (EV_ABS, EV_KEY, ...)
1102 * @param code The event code to enable (ABS_X, REL_X, etc.)
1103 * @param data If type is EV_ABS, data points to a struct input_absinfo. If type is EV_REP, data
1104 * points to an integer. Otherwise, data must be NULL.
1106 * @return 0 on success or -1 otherwise
1108 * @see libevdev_enable_event_type
1110 int libevdev_enable_event_code(struct libevdev *dev, unsigned int type, unsigned int code, const void *data);
1115 * Forcibly disable an event code on this device, even if the underlying
1116 * device provides it. This effectively mutes the respective set of
1117 * events. libevdev will filter any events matching this type and code and
1118 * none will reach the caller. libevdev_has_event_code() will return false for
1121 * Disabling all event codes for a given type will not disable the event
1122 * type. Use libevdev_disable_event_type() for that.
1124 * This is a local modification only affecting only this representation of
1127 * Disabling EV_SYN will not work. Don't shoot yourself in the foot.
1130 * @param dev The evdev device, already initialized with libevdev_set_fd()
1131 * @param type The event type to disable (EV_ABS, EV_KEY, ...)
1132 * @param code The event code to disable (ABS_X, REL_X, etc.)
1134 * @return 0 on success or -1 otherwise
1136 * @see libevdev_has_event_code
1137 * @see libevdev_disable_event_type
1139 int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigned int code);
1144 * Set the device's EV_ABS axis to the value defined in the abs
1145 * parameter. This will be written to the kernel.
1147 * @param dev The evdev device, already initialized with libevdev_set_fd()
1148 * @param code The EV_ABS event code to modify, one of ABS_X, ABS_Y, etc.
1149 * @param abs Axis info to set the kernel axis to
1151 * @return zero on success, or a negative errno on failure
1153 * @see libevdev_enable_event_code
1155 int libevdev_kernel_set_abs_info(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs);
1158 enum libevdev_led_value {
1159 LIBEVDEV_LED_ON = 3,
1160 LIBEVDEV_LED_OFF = 4,
1166 * Turn an LED on or off. Convenience function, if you need to modify multiple
1167 * LEDs simultaneously, use libevdev_kernel_set_led_values() instead.
1169 * @note enabling an LED requires write permissions on the device's file descriptor.
1171 * @param dev The evdev device, already initialized with libevdev_set_fd()
1172 * @param code The EV_LED event code to modify, one of LED_NUML, LED_CAPSL, ...
1173 * @param value Specifies whether to turn the LED on or off
1174 * @return zero on success, or a negative errno on failure
1176 int libevdev_kernel_set_led_value(struct libevdev *dev, unsigned int code, enum libevdev_led_value value);
1181 * Turn multiple LEDs on or off simultaneously. This function expects a pair
1182 * of LED codes and values to set them to, terminated by a -1. For example, to
1183 * switch the NumLock LED on but the CapsLock LED off, use:
1186 * libevdev_kernel_set_led_values(dev, LED_NUML, LIBEVDEV_LED_ON,
1187 * LED_CAPSL, LIBEVDEV_LED_OFF,
1191 * If any LED code or value is invalid, this function returns -EINVAL and no
1192 * LEDs are modified.
1194 * @note enabling an LED requires write permissions on the device's file descriptor.
1196 * @param dev The evdev device, already initialized with libevdev_set_fd()
1197 * @param ... A pair of LED_* event codes and libevdev_led_value_t, followed by
1198 * -1 to terminate the list.
1199 * @return zero on success, or a negative errno on failure
1201 int libevdev_kernel_set_led_values(struct libevdev *dev, ...);
1206 * Helper function to check if an event is of a specific type. This is
1207 * virtually the same as:
1211 * with the exception that some sanity checks are performed to ensure type
1214 * @param ev The input event to check
1215 * @param type Input event type to compare the event against (EV_REL, EV_ABS,
1218 * @return 1 if the event type matches the given type, 0 otherwise (or if
1221 int libevdev_is_event_type(const struct input_event *ev, unsigned int type);
1226 * Helper function to check if an event is of a specific type and code. This
1227 * is virtually the same as:
1229 * ev->type == type && ev->code == code
1231 * with the exception that some sanity checks are performed to ensure type and
1234 * @param ev The input event to check
1235 * @param type Input event type to compare the event against (EV_REL, EV_ABS,
1237 * @param code Input event code to compare the event against (ABS_X, REL_X,
1240 * @return 1 if the event type matches the given type and code, 0 otherwise
1241 * (or if type/code are invalid)
1243 int libevdev_is_event_code(const struct input_event *ev, unsigned int type, unsigned int code);
1248 * @param type The event type to return the name for.
1250 * @return The name of the given event type (e.g. EV_ABS) or NULL for an
1253 * @note The list of names is compiled into libevdev. If the kernel adds new
1254 * defines for new properties libevdev will not automatically pick these up.
1256 const char * libevdev_get_event_type_name(unsigned int type);
1260 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.)
1261 * @param code The event code to return the name for (e.g. ABS_X)
1263 * @return The name of the given event code (e.g. ABS_X) or NULL for an
1264 * invalid type or code
1266 * @note The list of names is compiled into libevdev. If the kernel adds new
1267 * defines for new properties libevdev will not automatically pick these up.
1269 const char * libevdev_get_event_code_name(unsigned int type, unsigned int code);
1274 * @param prop The input prop to return the name for (e.g. INPUT_PROP_BUTTONPAD)
1276 * @return The name of the given input prop (e.g. INPUT_PROP_BUTTONPAD) or NULL for an
1279 * @note The list of names is compiled into libevdev. If the kernel adds new
1280 * defines for new properties libevdev will not automatically pick these up.
1281 * @note On older kernels input properties may not be defined and
1282 * libevdev_get_input_prop_name() will always return NULL
1284 const char* libevdev_get_property_name(unsigned int prop);
1289 * @param type The event type to return the maximum for (EV_ABS, EV_REL, etc.). No max is defined for
1292 * @return The max value defined for the given event type, e.g. ABS_MAX for a type of EV_ABS, or -1
1293 * for an invalid type.
1295 * @note The max value is compiled into libevdev. If the kernel changes the
1296 * max value, libevdev will not automatically pick these up.
1298 int libevdev_get_event_type_max(unsigned int type);
1303 * Get the repeat delay and repeat period values for this device.
1305 * @param dev The evdev device, already initialized with libevdev_set_fd()
1306 * @param delay If not null, set to the repeat delay value
1307 * @param period If not null, set to the repeat period value
1309 * @return 0 on success, -1 if this device does not have repeat settings.
1311 * @note This function is signal-safe
1313 int libevdev_get_repeat(struct libevdev *dev, int *delay, int *period);
1316 /********* DEPRECATED SECTION *********/
1317 #if defined(__GNUC__) && __GNUC__ >= 4
1318 #define LIBEVDEV_DEPRECATED __attribute__ ((deprecated))
1320 #define LIBEVDEV_DEPRECATED
1323 /* replacement: libevdev_get_abs_minimum */
1324 int libevdev_get_abs_min(const struct libevdev *dev, unsigned int code) LIBEVDEV_DEPRECATED;
1325 /* replacement: libevdev_get_abs_maximum */
1326 int libevdev_get_abs_max(const struct libevdev *dev, unsigned int code) LIBEVDEV_DEPRECATED;
1328 /* replacement: libevdev_get_property_name */
1329 const char* libevdev_get_input_prop_name(unsigned int prop) LIBEVDEV_DEPRECATED;
1331 int libevdev_get_product_id(const struct libevdev *dev) LIBEVDEV_DEPRECATED;
1332 int libevdev_get_vendor_id(const struct libevdev *dev) LIBEVDEV_DEPRECATED;
1333 int libevdev_get_bustype(const struct libevdev *dev) LIBEVDEV_DEPRECATED;
1334 int libevdev_get_version(const struct libevdev *dev) LIBEVDEV_DEPRECATED;
1336 /* replacement: libevdev_kernel_set_abs_info */
1337 int libevdev_kernel_set_abs_value(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs) LIBEVDEV_DEPRECATED;
1340 /**************************************/
1341 #endif /* LIBEVDEV_H */