evdev-rs/README.md

`evdev`
=======

[![Travis](https://img.shields.io/travis/cmr/evdev.svg?style=flat-square)](https://travis-ci.org/cmr/evdev)
[![Crates.io](https://img.shields.io/crates/v/evdev.svg?style=flat-square)](https://crates.io/crates/evdev)

[Documentation](https://docs.rs/evdev)

Nice(r) access to `evdev` devices.

What is `evdev`?
===================

`evdev` is the Linux kernel's generic input interface, also implemented by other
kernels such as FreeBSD.

This crate exposes access to these sorts of input devices. There is some trickery
involved, so please read the crate documentation.

What does this library support?
===============================

This library exposes raw evdev events, but uses the Rust `Iterator` trait to
do so. When processing events via `fetch_events`, the library will handle
`SYN_DROPPED` events by injecting fake state updates in an attempt to ensure
callers see state transition messages consistent with actual device state. When
processing via `*_no_sync` this correction is not done, and `SYN_DROPPED` messages
will appear if the kernel ring buffer is overrun before messages are read. I try to
match [libevdev](https://www.freedesktop.org/software/libevdev/doc/latest/)
closely, where possible.

Writing to devices is not yet supported (eg, turning LEDs on).

There is no abstraction for gamepad-like devices that allows mapping button
numbers to logical buttons, nor is one planned. Such a thing should take place
in a higher-level crate, likely supporting multiple platforms.

Example
=======

See <examples/evtest.rs> for an example of using this library (which roughly
corresponds to the userspace [evtest](https://cgit.freedesktop.org/evtest/)
tool.
Underp the readme title 2015-07-18 19:26:23 +00:00			`evdev`
Initial commit 2015-05-29 18:57:46 +00:00			`=======`

Fix badge links 2015-07-21 11:39:03 +00:00			`[![Travis](https://img.shields.io/travis/cmr/evdev.svg?style=flat-square)](https://travis-ci.org/cmr/evdev)`
			`[![Crates.io](https://img.shields.io/crates/v/evdev.svg?style=flat-square)](https://crates.io/crates/evdev)`
Initial commit 2015-05-29 18:57:46 +00:00
Fix all the current issues: Changes in Rust, changes in the evdev ABI, and a bug 2017-04-27 23:42:45 +00:00			`[Documentation](https://docs.rs/evdev)`
Initial commit 2015-05-29 18:57:46 +00:00
Fix all the current issues: Changes in Rust, changes in the evdev ABI, and a bug 2017-04-27 23:42:45 +00:00			Nice(r) access to `evdev` devices.
Initial commit 2015-05-29 18:57:46 +00:00
			What is `evdev`?
			`===================`

Update nix to 0.9, support FreeBSD nix 0.9's ioctl macro works with buffers now. 2017-12-01 19:44:06 +00:00			`evdev` is the Linux kernel's generic input interface, also implemented by other
			`kernels such as FreeBSD.`

			`This crate exposes access to these sorts of input devices. There is some trickery`
			`involved, so please read the crate documentation.`
Initial commit 2015-05-29 18:57:46 +00:00
			`What does this library support?`
			`===============================`

Update README and evtest 2015-07-21 09:33:40 +00:00			This library exposes raw evdev events, but uses the Rust `Iterator` trait to
Separate out sane blocking and async (nonblocking) implementations (#33) * Default impl should block. Renaming it to avoid API confusion from previous users. * Can't get rid of libc::read because we have MaybeUninit, but we can clean up the match * Remove extra include * Switch everything over to io::Error * Add initial tokio impl+example * Move evtest_tokio to normal example * Add documentation and clarify * Use a VecDeque (ring buffer) instead of repeatedly popping things off the front of a Vec * Looks like we are not using thiserror anymore; removing * Store read buf between calls * Add nonblocking example with epoll Co-authored-by: Jeff Hiner <jeff-hiner@users.noreply.github.com> Co-authored-by: Noah <33094578+coolreader18@users.noreply.github.com> 2021-03-01 17:09:11 +00:00			do so. When processing events via `fetch_events`, the library will handle
			`SYN_DROPPED` events by injecting fake state updates in an attempt to ensure
			`callers see state transition messages consistent with actual device state. When`
			processing via `*_no_sync` this correction is not done, and `SYN_DROPPED` messages
			`will appear if the kernel ring buffer is overrun before messages are read. I try to`
Update nix to 0.9, support FreeBSD nix 0.9's ioctl macro works with buffers now. 2017-12-01 19:44:06 +00:00			`match [libevdev](https://www.freedesktop.org/software/libevdev/doc/latest/)`
Update README and evtest 2015-07-21 09:33:40 +00:00			`closely, where possible.`

			`Writing to devices is not yet supported (eg, turning LEDs on).`
Initial commit 2015-05-29 18:57:46 +00:00
Fix all the current issues: Changes in Rust, changes in the evdev ABI, and a bug 2017-04-27 23:42:45 +00:00			`There is no abstraction for gamepad-like devices that allows mapping button`
			`numbers to logical buttons, nor is one planned. Such a thing should take place`
			`in a higher-level crate, likely supporting multiple platforms.`

Initial commit 2015-05-29 18:57:46 +00:00			`Example`
			`=======`

Update README and evtest 2015-07-21 09:33:40 +00:00			`See <examples/evtest.rs> for an example of using this library (which roughly`
Update nix to 0.9, support FreeBSD nix 0.9's ioctl macro works with buffers now. 2017-12-01 19:44:06 +00:00			`corresponds to the userspace [evtest](https://cgit.freedesktop.org/evtest/)`
Update README and evtest 2015-07-21 09:33:40 +00:00			`tool.`