1<!-- HTML header for doxygen 1.8.8--> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="X-UA-Compatible" content="IE=edge"> 6 <!-- For Mobile Devices --> 7 <meta name="viewport" content="width=device-width, initial-scale=1"> 8 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> 9 <meta name="generator" content="Doxygen 1.9.1"/> 10 <script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script> 11 <title>libevdev: Main Page</title> 12 <!--<link href="tabs.css" rel="stylesheet" type="text/css"/>--> 13 <script type="text/javascript" src="dynsections.js"></script> 14 <link href="search/search.css" rel="stylesheet" type="text/css"/> 15<script type="text/javascript" src="search/searchdata.js"></script> 16<script type="text/javascript" src="search/search.js"></script> 17 <link href="doxygen.css" rel="stylesheet" type="text/css" /> 18 <link href="bootstrap.css" rel="stylesheet" type="text/css"/> 19<link href="customdoxygen.css" rel="stylesheet" type="text/css"/> 20<link href="libevdevdoxygen.css" rel="stylesheet" type="text/css"/> 21 <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/js/bootstrap.min.js"></script> 22 <script type="text/javascript" src="doxy-boot.js"></script> 23 </head> 24 <body> 25 <nav class="navbar navbar-default" role="navigation"> 26 <div class="container"> 27 <div class="navbar-header"> 28 <a class="navbar-brand">libevdev 1.12.1</a> 29 </div> 30 </div> 31 </nav> 32 <div id="top"><!-- do not remove this div, it is closed by doxygen! --> 33 <div class="content" id="content"> 34 <div class="container"> 35 <div class="row"> 36 <div class="col-sm-12 panel panel-default" style="padding-bottom: 15px;"> 37 <div style="margin-bottom: 15px;"> 38<!-- end header part --> 39<!-- Generated by Doxygen 1.9.1 --> 40<script type="text/javascript"> 41/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 42var searchBox = new SearchBox("searchBox", "search",false,'Search','.html'); 43/* @license-end */ 44</script> 45<script type="text/javascript" src="menudata.js"></script> 46<script type="text/javascript" src="menu.js"></script> 47<script type="text/javascript"> 48/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 49$(function() { 50 initMenu('',true,false,'search.php','Search'); 51 $(document).ready(function() { init_search(); }); 52}); 53/* @license-end */</script> 54<div id="main-nav"></div> 55</div><!-- top --> 56<!-- window showing the filter options --> 57<div id="MSearchSelectWindow" 58 onmouseover="return searchBox.OnSearchSelectShow()" 59 onmouseout="return searchBox.OnSearchSelectHide()" 60 onkeydown="return searchBox.OnSearchSelectKey(event)"> 61</div> 62 63<!-- iframe showing the search results (closed by default) --> 64<div id="MSearchResultsWindow"> 65<iframe src="javascript:void(0)" frameborder="0" 66 name="MSearchResults" id="MSearchResults"> 67</iframe> 68</div> 69 70<div class="PageDoc"><div class="header"> 71 <div class="headertitle"> 72<div class="title">libevdev Documentation</div> </div> 73</div><!--header--> 74<div class="contents"> 75<div class="textblock"><p><b>libevdev</b> is a library for handling evdev kernel devices. It abstracts the <a class="el" href="ioctls.html">evdev ioctls</a> through type-safe interfaces and provides functions to change the appearance of the device.</p> 76<h1><a class="anchor" id="autotoc_md0"></a> 77Development</h1> 78<p>The git repository is available here:</p> 79<ul> 80<li><a href="https://gitlab.freedesktop.org/libevdev/libevdev">https://gitlab.freedesktop.org/libevdev/libevdev</a></li> 81</ul> 82<p>Development of libevdev is discussed on <a href="http://lists.freedesktop.org/mailman/listinfo/input-tools">input-tools@lists.freedesktop.org</a>. Please submit patches, questions or general comments there.</p> 83<h1><a class="anchor" id="autotoc_md1"></a> 84Handling events and SYN_DROPPED</h1> 85<p>libevdev provides an interface for handling events, including most notably <code>SYN_DROPPED</code> events. <code>SYN_DROPPED</code> 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 * <code>SYN_DROPPED</code> 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 <a class="el" href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76" title="Get the next event from the device.">libevdev_next_event()</a> and <a class="el" href="syn_dropped.html">SYN_DROPPED handling</a> for more information on how <code>SYN_DROPPED</code> is handled.</p> 86<h1><a class="anchor" id="autotoc_md2"></a> 87Signal safety</h1> 88<p>libevdev is signal-safe for the majority of its operations, i.e. many of its functions are safe to be called from within a signal handler. Check the API documentation to make sure, unless explicitly stated a call is <b>not</b> signal safe.</p> 89<h1><a class="anchor" id="autotoc_md3"></a> 90Device handling</h1> 91<p>A libevdev context is valid for a given file descriptor and its duration. Closing the file descriptor will not destroy the libevdev device but libevdev will not be able to read further events.</p> 92<p>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.</p> 93<p>libevdev does not handle the file descriptors directly, it merely uses them. The caller is responsible for opening the file descriptors, setting them to <code>O_NONBLOCK</code> and handling permissions. A caller should drain any events pending on the file descriptor before passing it to libevdev.</p> 94<h1><a class="anchor" id="autotoc_md4"></a> 95Where does libevdev sit?</h1> 96<p>libevdev is essentially a <code>read(2)</code> on steroids for <code>/dev/input/eventX</code> 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: </p><pre class="fragment"> kernel → libevdev → evtest 97</pre><p> For X.Org input modules, the stack would look like this: </p><pre class="fragment"> kernel → libevdev → xf86-input-evdev → X server → X client 98</pre><p> For anything using libinput (e.g. most Wayland compositors), the stack the stack would look like this: </p><pre class="fragment"> kernel → libevdev → libinput → Compositor → Wayland client 99</pre><p> libevdev does <b>not</b> have knowledge of X clients or Wayland clients, it is too low in the stack.</p> 100<h1><a class="anchor" id="autotoc_md5"></a> 101Example</h1> 102<p>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.</p> 103<div class="fragment"><div class="line"><span class="keyword">struct </span>libevdev *dev = NULL;</div> 104<div class="line"><span class="keywordtype">int</span> fd;</div> 105<div class="line"><span class="keywordtype">int</span> rc = 1;</div> 106<div class="line"> </div> 107<div class="line">fd = open(<span class="stringliteral">"/dev/input/event0"</span>, O_RDONLY|O_NONBLOCK);</div> 108<div class="line">rc = <a class="code" href="group__init.html#ga89bb5bce1c23e293293484b05b12aaf4">libevdev_new_from_fd</a>(fd, &dev);</div> 109<div class="line"><span class="keywordflow">if</span> (rc < 0) {</div> 110<div class="line"> fprintf(stderr, <span class="stringliteral">"Failed to init libevdev (%s)\n"</span>, strerror(-rc));</div> 111<div class="line"> exit(1);</div> 112<div class="line">}</div> 113<div class="line">printf(<span class="stringliteral">"Input device name: \"%s\"\n"</span>, <a class="code" href="group__bits.html#gaed0328c67b7a78422636d9fe09a73f12">libevdev_get_name</a>(dev));</div> 114<div class="line">printf(<span class="stringliteral">"Input device ID: bus %#x vendor %#x product %#x\n"</span>,</div> 115<div class="line"> <a class="code" href="group__bits.html#ga9bf55d416401642bad0c435735682308">libevdev_get_id_bustype</a>(dev),</div> 116<div class="line"> <a class="code" href="group__bits.html#ga08891c3285da5b8d26769c9a34f063f3">libevdev_get_id_vendor</a>(dev),</div> 117<div class="line"> <a class="code" href="group__bits.html#ga1dc66cfef646878d58be72f8902a6bac">libevdev_get_id_product</a>(dev));</div> 118<div class="line"><span class="keywordflow">if</span> (!<a class="code" href="group__bits.html#ga398bef155fa4a0cfb832de30723ebd14">libevdev_has_event_type</a>(dev, EV_REL) ||</div> 119<div class="line"> !<a class="code" href="group__bits.html#gab2ab9dad417f33daa79fa0c3d682df0b">libevdev_has_event_code</a>(dev, EV_KEY, BTN_LEFT)) {</div> 120<div class="line"> printf(<span class="stringliteral">"This device does not look like a mouse\n"</span>);</div> 121<div class="line"> exit(1);</div> 122<div class="line">}</div> 123<div class="line"> </div> 124<div class="line"><span class="keywordflow">do</span> {</div> 125<div class="line"> <span class="keyword">struct </span>input_event ev;</div> 126<div class="line"> rc = <a class="code" href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76">libevdev_next_event</a>(dev, <a class="code" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9ac0d6ee19551eecf76f1ede4f36252418">LIBEVDEV_READ_FLAG_NORMAL</a>, &ev);</div> 127<div class="line"> <span class="keywordflow">if</span> (rc == 0)</div> 128<div class="line"> printf(<span class="stringliteral">"Event: %s %s %d\n"</span>,</div> 129<div class="line"> <a class="code" href="group__misc.html#gac99720fd926bf288764f9a81bf37ed09">libevdev_event_type_get_name</a>(ev.type),</div> 130<div class="line"> <a class="code" href="group__misc.html#gab407b3c2caaae502859c28460cad17bb">libevdev_event_code_get_name</a>(ev.type, ev.code),</div> 131<div class="line"> ev.value);</div> 132<div class="line">} <span class="keywordflow">while</span> (rc == 1 || rc == 0 || rc == -EAGAIN);</div> 133<div class="ttc" id="agroup__bits_html_ga08891c3285da5b8d26769c9a34f063f3"><div class="ttname"><a href="group__bits.html#ga08891c3285da5b8d26769c9a34f063f3">libevdev_get_id_vendor</a></div><div class="ttdeci">int libevdev_get_id_vendor(const struct libevdev *dev)</div></div> 134<div class="ttc" id="agroup__bits_html_ga1dc66cfef646878d58be72f8902a6bac"><div class="ttname"><a href="group__bits.html#ga1dc66cfef646878d58be72f8902a6bac">libevdev_get_id_product</a></div><div class="ttdeci">int libevdev_get_id_product(const struct libevdev *dev)</div></div> 135<div class="ttc" id="agroup__bits_html_ga398bef155fa4a0cfb832de30723ebd14"><div class="ttname"><a href="group__bits.html#ga398bef155fa4a0cfb832de30723ebd14">libevdev_has_event_type</a></div><div class="ttdeci">int libevdev_has_event_type(const struct libevdev *dev, unsigned int type)</div></div> 136<div class="ttc" id="agroup__bits_html_ga9bf55d416401642bad0c435735682308"><div class="ttname"><a href="group__bits.html#ga9bf55d416401642bad0c435735682308">libevdev_get_id_bustype</a></div><div class="ttdeci">int libevdev_get_id_bustype(const struct libevdev *dev)</div></div> 137<div class="ttc" id="agroup__bits_html_gab2ab9dad417f33daa79fa0c3d682df0b"><div class="ttname"><a href="group__bits.html#gab2ab9dad417f33daa79fa0c3d682df0b">libevdev_has_event_code</a></div><div class="ttdeci">int libevdev_has_event_code(const struct libevdev *dev, unsigned int type, unsigned int code)</div></div> 138<div class="ttc" id="agroup__bits_html_gaed0328c67b7a78422636d9fe09a73f12"><div class="ttname"><a href="group__bits.html#gaed0328c67b7a78422636d9fe09a73f12">libevdev_get_name</a></div><div class="ttdeci">const char * libevdev_get_name(const struct libevdev *dev)</div><div class="ttdoc">Retrieve the device's name, either as set by the caller or as read from the kernel.</div></div> 139<div class="ttc" id="agroup__events_html_gabb96c864e836c0b98788f4ab771c3a76"><div class="ttname"><a href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76">libevdev_next_event</a></div><div class="ttdeci">int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_event *ev)</div><div class="ttdoc">Get the next event from the device.</div></div> 140<div class="ttc" id="agroup__events_html_gga56c288d9f2e4c1632986c4e218c494e9ac0d6ee19551eecf76f1ede4f36252418"><div class="ttname"><a href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9ac0d6ee19551eecf76f1ede4f36252418">LIBEVDEV_READ_FLAG_NORMAL</a></div><div class="ttdeci">@ LIBEVDEV_READ_FLAG_NORMAL</div><div class="ttdoc">Process data in normal mode.</div><div class="ttdef"><b>Definition:</b> libevdev.h:762</div></div> 141<div class="ttc" id="agroup__init_html_ga89bb5bce1c23e293293484b05b12aaf4"><div class="ttname"><a href="group__init.html#ga89bb5bce1c23e293293484b05b12aaf4">libevdev_new_from_fd</a></div><div class="ttdeci">int libevdev_new_from_fd(int fd, struct libevdev **dev)</div><div class="ttdoc">Initialize a new libevdev device from the given fd.</div></div> 142<div class="ttc" id="agroup__misc_html_gab407b3c2caaae502859c28460cad17bb"><div class="ttname"><a href="group__misc.html#gab407b3c2caaae502859c28460cad17bb">libevdev_event_code_get_name</a></div><div class="ttdeci">const char * libevdev_event_code_get_name(unsigned int type, unsigned int code)</div></div> 143<div class="ttc" id="agroup__misc_html_gac99720fd926bf288764f9a81bf37ed09"><div class="ttname"><a href="group__misc.html#gac99720fd926bf288764f9a81bf37ed09">libevdev_event_type_get_name</a></div><div class="ttdeci">const char * libevdev_event_type_get_name(unsigned int type)</div></div> 144</div><!-- fragment --><p>A more complete example is available with the libevdev-events tool here: <a href="https://gitlab.freedesktop.org/libevdev/libevdev/blob/master/tools/libevdev-events.c">https://gitlab.freedesktop.org/libevdev/libevdev/blob/master/tools/libevdev-events.c</a></p> 145<h1><a class="anchor" id="autotoc_md6"></a> 146Backwards compatibility with older kernel</h1> 147<p>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 <a class="el" href="backwardscompatibility.html">Compatibility and Behavior across kernel versions</a>.</p> 148<h1><a class="anchor" id="autotoc_md7"></a> 149License information</h1> 150<p>libevdev is licensed under the <a href="http://cgit.freedesktop.org/libevdev/tree/COPYING">X11 license</a>.</p> 151<h1><a class="anchor" id="autotoc_md8"></a> 152Bindings</h1> 153<ul> 154<li>Python: <a href="https://gitlab.freedesktop.org/libevdev/python-libevdev">https://gitlab.freedesktop.org/libevdev/python-libevdev</a></li> 155<li>Haskell: <a href="http://hackage.haskell.org/package/evdev">http://hackage.haskell.org/package/evdev</a></li> 156<li>Rust: <a href="https://crates.io/crates/evdev-rs">https://crates.io/crates/evdev-rs</a></li> 157</ul> 158<h1><a class="anchor" id="autotoc_md9"></a> 159Reporting bugs</h1> 160<p>Please report bugs in the freedesktop.org GitLab instance: <a href="https://gitlab.freedesktop.org/libevdev/libevdev/issues/">https://gitlab.freedesktop.org/libevdev/libevdev/issues/</a> </p> 161</div></div><!-- PageDoc --> 162</div><!-- contents --> 163<!-- HTML footer for doxygen 1.8.8--> 164<!-- start footer part --> 165</div> 166</div> 167</div> 168</div> 169</div> 170<hr class="footer"/><address class="footer"><small> 171Generated by  <a href="http://www.doxygen.org/index.html"> 172<img class="footer" src="doxygen.png" alt="doxygen"/> 173</a> 1.9.1 174</small></address> 175</body> 176</html> 177
