libevdev Documentation

libevdev is a library for handling evdev kernel devices. It abstracts the ioctls through type-safe interfaces and provides functions to change the appearance of the device.

Development of libevdev is discussed on input-tools@lists.freedesktop.org Please submit patches, questions or general comments there.

Handling events and SYN_DROPPED

libevdev provides an interface for handling events, including most notably SYN_DROPPED events. SYN_DROPPED events are sent by the kernel when the process does not read events fast enough and the kernel is forced to drop some events. This causes the device to get out of sync with the process' view of it. libevdev handles this by telling the caller that a SYN_DROPPED has been received and that the state of the device is different to what is to be expected. It then provides the delta between the previous state and the actual state of the device as a set of events. See libevdev_next_event() for more information.

Signal safety

libevdev is signal-safe for the majority of its operations. Check the API documentation to make sure, unless explicitly stated a call is not signal safe.

Device handling

libevdev does not attempt duplicate detection. Initializing two libevdev devices for the same fd is valid and behaves the same as for two different devices.

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.

Where does libevdev sit?

libevdev is essentially a read(2) on steroids for `/dev/input/eventX devices. It sits below the process that handles input events, in between the kernel and that process. In the simplest case, e.g. an evtest-like tool the stack would look like this:

 kernel → libevdev → evtest

For X.Org input modules, the stack would look like this:

 kernel → libevdev → xf86-input-evdev → X server → X client

For Weston/Wayland, the stack would look like this:

 kernel → libevdev → Weston → Wayland client

libevdev does not have knowledge of X clients or Wayland clients, it is too low in the stack.

Example

Below is a simple example that shows how libevdev could be used. This example opens a device, checks for relative axes and a left mouse button and if it finds them monitors the device to print the event.

struct libevdev *dev = NULL;
int fd;
int rc = 1;

fd = open("/dev/input/event0", O_RDONLY|O_NONBLOCK);
rc = libevdev_new_from_fd(fd, &dev);
if (rc < 0) {
        fprintf(stderr, "Failed to init libevdev (%s)\n", strerror(-rc));
        exit(1);
}
printf("Input device name: \"%s\"\n", libevdev_get_name(dev));
printf("Input device ID: bus %#x vendor %#x product %#x\n",
       libevdev_get_id_bustype(dev),
       libevdev_get_id_vendor(dev),
       libevdev_get_id_product(dev));
if (!libevdev_has_event_type(dev, EV_REL) ||
    !libevdev_has_event_code(dev, EV_KEY, BTN_LEFT)) {
        printf("This device does not look like a mouse\n");
        exit(1);
}

do {
        struct input_event ev;
        rc = libevdev_next_event(dev, LIBEVDEV_READ_FLAG_NORMAL, &ev);
        if (rc == 0)
                printf("Event: %s %s %d\n",
                       libevdev_get_event_type_name(ev.type),
                       libevdev_get_event_code_name(ev.type, ev.code),
                       ev.value);
} while (rc == 1 || rc == 0 || rc == -EAGAIN);

A more complete example is available with the libevdev-events tool here: http://cgit.freedesktop.org/libevdev/tree/tools/libevdev-events.c

Backwards compatibility with older kernel

libevdev attempts to build and run correctly on a number of kernel versions. If features required are not available, libevdev attempts to work around them in the most reasonable way. For more details see Compatibility and Behavior across kernel versions.

libevdev internal test suite

libevdev's internal test suite uses the Check unit testing framework. Tests are divided into test suites and test cases. Most tests create a uinput device, so you'll need to run as root.

To run a specific suite only:

export CK_RUN_SUITE="suite name"

To run a specific test case only:

export CK_RUN_TEST="test case name"

To get a list of all suites or tests:

git grep "suite_create"
git grep "tcase_create"

By default, check forks, making debugging harder. Run gdb as below to avoid forking.

sudo CK_FORK=no CK_RUN_TEST="test case name" gdb ./test/test-libevdev

A special target make gcov-report.txt exists that runs gcov and leaves a libevdev.c.gcov file. Check that for test coverage.

make check is hooked up to run the test and gcov (again, needs root).

The test suite creates a lot of devices, very quickly. Add the following xorg.conf.d snippet to avoid the devices being added as X devices (at the time of writing, mutter can't handle these devices and exits after getting a BadDevice error).

$ cat /etc/X11/xorg.conf.d/99-ignore-libevdev-devices.conf
Section "InputClass"
        Identifier "Ignore libevdev test devices"
        MatchProduct "libevdev test device"
        Option "Ignore" "on"
EndSection

License information

libevdev is licensed under the X11 license.

Reporting bugs

Please report bugs in the freedesktop.org bugzilla under the libevdev product: https://bugs.freedesktop.org/enter_bug.cgi?product=libevdev