-
-
Notifications
You must be signed in to change notification settings - Fork 242
Expand file tree
/
Copy pathlibevdev.h
More file actions
2387 lines (2277 loc) · 87.1 KB
/
libevdev.h
File metadata and controls
2387 lines (2277 loc) · 87.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/* SPDX-License-Identifier: MIT */
/*
* Copyright © 2013 Red Hat, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to
* deal in the Software without restriction, including without limitation the
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
* sell copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice (including the next
* paragraph) shall be included in all copies or substantial portions of the
* Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
* IN THE SOFTWARE.
*
*/
#ifndef LIBEVDEV_H
#define LIBEVDEV_H
#ifdef __cplusplus
extern "C" {
#endif
#include <linux/input.h>
#include <stdarg.h>
#define LIBEVDEV_ATTRIBUTE_PRINTF(_format, _args) __attribute__ ((format (printf, _format, _args)))
/**
* @mainpage
*
* **libevdev** is a library for handling evdev kernel devices. It abstracts
* the \ref ioctls through type-safe interfaces and provides functions to change
* the appearance of the device.
*
* Development
* ===========
* The git repository is available here:
*
* - https://gitlab.freedesktop.org/libevdev/libevdev
*
* Development of libevdev is discussed on
* [input-tools@lists.freedesktop.org](http://lists.freedesktop.org/mailman/listinfo/input-tools).
* 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() and @ref syn_dropped for more information on how
* `SYN_DROPPED` is handled.
*
* Signal safety
* =============
*
* 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.
*
* Device handling
* ===============
*
* 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.
*
* 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. A caller should drain any
* events pending on the file descriptor before passing it to libevdev.
*
* 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 anything using libinput (e.g. most Wayland compositors), the stack
* the stack would look like this:
*
* kernel → libevdev → libinput → Compositor → 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.
*
* @code
* 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_event_type_get_name(ev.type),
* libevdev_event_code_get_name(ev.type, ev.code),
* ev.value);
* } while (rc == 1 || rc == 0 || rc == -EAGAIN);
* @endcode
*
* A more complete example is available with the libevdev-events tool here:
* https://gitlab.freedesktop.org/libevdev/libevdev/blob/master/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 \ref backwardscompatibility.
*
* License information
* ===================
* libevdev is licensed under the
* [MIT license](http://cgit.freedesktop.org/libevdev/tree/COPYING).
*
* Bindings
* ===================
* - Python: https://gitlab.freedesktop.org/libevdev/python-libevdev
* - Haskell: http://hackage.haskell.org/package/evdev
* - Rust: https://crates.io/crates/evdev-rs
*
* Reporting bugs
* ==============
* Please report bugs in the freedesktop.org GitLab instance:
* https://gitlab.freedesktop.org/libevdev/libevdev/issues/
*/
/**
* @page syn_dropped SYN_DROPPED handling
*
* This page describes how libevdev handles `SYN_DROPPED` events.
*
* Receiving `SYN_DROPPED` events
* ==============================
*
* The kernel sends evdev events separated by an event of type `EV_SYN` and
* code `SYN_REPORT`. Such an event marks the end of a frame of hardware
* events. The number of events between `SYN_REPORT` events is arbitrary and
* depends on the hardware. An example event sequence may look like this:
* @code
* EV_ABS ABS_X 9
* EV_ABS ABS_Y 8
* EV_SYN SYN_REPORT 0
* ------------------------
* EV_ABS ABS_X 10
* EV_ABS ABS_Y 10
* EV_KEY BTN_TOUCH 1
* EV_SYN SYN_REPORT 0
* ------------------------
* EV_ABS ABS_X 11
* EV_SYN SYN_REPORT 0
* @endcode
*
* Events are handed to the client buffer as they appear, the kernel adjusts
* the buffer size to handle at least one full event. In the normal case,
* the client reads the event and the kernel can place the next event in the
* buffer. If the client is not fast enough, the kernel places an event of
* type `EV_SYN` and code `SYN_DROPPED` into the buffer, effectively notifying
* the client that some events were lost. The above example event sequence
* may look like this (note the missing/repeated events):
* @code
* EV_ABS ABS_X 9
* EV_ABS ABS_Y 8
* EV_SYN SYN_REPORT 0
* ------------------------
* EV_ABS ABS_X 10
* EV_ABS ABS_Y 10
* EV_SYN SYN_DROPPED 0
* EV_ABS ABS_Y 15
* EV_SYN SYN_REPORT 0
* ------------------------
* EV_ABS ABS_X 11
* EV_KEY BTN_TOUCH 0
* EV_SYN SYN_REPORT 0
* @endcode
*
* A `SYN_DROPPED` event may be recieved at any time in the event sequence.
* When a `SYN_DROPPED` event is received, the client must:
* * discard all events since the last `SYN_REPORT`
* * discard all events until including the next `SYN_REPORT`
* These event are part of incomplete event frames.
*
* Synchronizing the state of the device
* =====================================
*
* The handling of the device after a `SYN_DROPPED` depends on the available
* event codes. For all event codes of type `EV_REL`, no handling is
* necessary, there is no state attached. For all event codes of type
* `EV_KEY`, `EV_SW`, `EV_LED` and `EV_SND`, the matching @ref ioctls retrieve the
* current state. The caller must then compare the last-known state to the
* retrieved state and handle the deltas accordingly.
* libevdev simplifies this approach: if the state of the device has
* changed, libevdev generates an event for each code with the new value and
* passes it to the caller during libevdev_next_event() if
* @ref LIBEVDEV_READ_FLAG_SYNC is set.
*
* For events of type `EV_ABS` and an event code less than `ABS_MT_SLOT`, the
* handling of state changes is as described above. For events between
* `ABS_MT_SLOT` and `ABS_MAX`, the event handling differs.
* Slots are the vehicles to transport information for multiple simultaneous
* touchpoints on a device. Slots are re-used once a touchpoint has ended.
* The kernel sends an `ABS_MT_SLOT` event whenever the current slot
* changes; any event in the above axis range applies only to the currently
* active slot.
* Thus, an event sequence from a slot-capable device may look like this:
* @code
* EV_ABS ABS_MT_POSITION_Y 10
* EV_ABS ABS_MT_SLOT 1
* EV_ABS ABS_MT_POSITION_X 100
* EV_ABS ABS_MT_POSITION_Y 80
* EV_SYN SYN_REPORT 0
* @endcode
* Note the lack of `ABS_MT_SLOT`: the first `ABS_MT_POSITION_Y` applies to
* a slot opened previously, and is the only axis that changed for that
* slot. The touchpoint in slot 1 now has position `100/80`.
* The kernel does not provide events if a value does not change, and does
* not send `ABS_MT_SLOT` events if the slot does not change, or none of the
* values within a slot changes. A client must thus keep the state for each
* slot.
*
* If a `SYN_DROPPED` is received, the client must sync all slots
* individually and update its internal state. libevdev simplifies this by
* generating multiple events:
* * for each slot on the device, libevdev generates an
* `ABS_MT_SLOT` event with the value set to the slot number
* * for each event code between `ABS_MT_SLOT + 1` and `ABS_MAX` that changed
* state for this slot, libevdev generates an event for the new state
* * libevdev sends a final `ABS_MT_SLOT` event for the current slot as
* seen by the kernel
* * libevdev terminates this sequence with an `EV_SYN SYN_REPORT` event
*
* An example event sequence for such a sync may look like this:
* @code
* EV_ABS ABS_MT_SLOT 0
* EV_ABS ABS_MT_POSITION_Y 10
* EV_ABS ABS_MT_SLOT 1
* EV_ABS ABS_MT_POSITION_X 100
* EV_ABS ABS_MT_POSITION_Y 80
* EV_ABS ABS_MT_SLOT 2
* EV_ABS ABS_MT_POSITION_Y 8
* EV_ABS ABS_MT_PRESSURE 12
* EV_ABS ABS_MT_SLOT 1
* EV_SYN SYN_REPORT 0
* @endcode
* Note the terminating `ABS_MT_SLOT` event, this indicates that the kernel
* currently has slot 1 active.
*
* Synchronizing ABS_MT_TRACKING_ID
* ================================
*
* The event code `ABS_MT_TRACKING_ID` is used to denote the start and end of
* a touch point within a slot. An `ABS_MT_TRACKING_ID` of zero or greater
* denotes the start of a touchpoint, an `ABS_MT_TRACKING_ID` of -1 denotes
* the end of a touchpoint within this slot. During `SYN_DROPPED`, a touch
* point may have ended and re-started within a slot - a client must check
* the `ABS_MT_TRACKING_ID`. libevdev simplifies this by emulating extra
* events if the `ABS_MT_TRACKING_ID` has changed:
* * if the `ABS_MT_TRACKING_ID` was valid and is -1, libevdev enqueues an
* `ABS_MT_TRACKING_ID` event with value -1.
* * if the `ABS_MT_TRACKING_ID` was -1 and is now a valid ID, libevdev
* enqueues an `ABS_MT_TRACKING_ID` event with the current value.
* * if the `ABS_MT_TRACKING_ID` was a valid ID and is now a different valid
* ID, libevev enqueues an `ABS_MT_TRACKING_ID` event with value -1 and
* another `ABS_MT_TRACKING_ID` event with the new value.
*
* An example event sequence for such a sync may look like this:
* @code
* EV_ABS ABS_MT_SLOT 0
* EV_ABS ABS_MT_TRACKING_ID -1
* EV_ABS ABS_MT_SLOT 2
* EV_ABS ABS_MT_TRACKING_ID -1
* EV_SYN SYN_REPORT 0
* ------------------------
* EV_ABS ABS_MT_SLOT 1
* EV_ABS ABS_MT_POSITION_X 100
* EV_ABS ABS_MT_POSITION_Y 80
* EV_ABS ABS_MT_SLOT 2
* EV_ABS ABS_MT_TRACKING_ID 45
* EV_ABS ABS_MT_POSITION_Y 8
* EV_ABS ABS_MT_PRESSURE 12
* EV_ABS ABS_MT_SLOT 1
* EV_SYN SYN_REPORT 0
* @endcode
* Note how the touchpoint in slot 0 was terminated, the touchpoint in slot
* 2 was terminated and then started with a new `ABS_MT_TRACKING_ID`. The touchpoint
* in slot 1 maintained the same `ABS_MT_TRACKING_ID` and only updated the
* coordinates. Slot 1 is the currently active slot.
*
* In the case of a `SYN_DROPPED` event, a touch point may be invisible to a
* client if it started after `SYN_DROPPED` and finished before the client
* handles events again. The below example shows an example event sequence
* and what libevdev sees in the case of a `SYN_DROPPED` event:
* @code
*
* kernel | userspace
* |
* EV_ABS ABS_MT_SLOT 0 | EV_ABS ABS_MT_SLOT 0
* EV_ABS ABS_MT_TRACKING_ID -1 | EV_ABS ABS_MT_TRACKING_ID -1
* EV_SYN SYN_REPORT 0 | EV_SYN SYN_REPORT 0
* ------------------------ | ------------------------
* EV_ABS ABS_MT_TRACKING_ID 30 |
* EV_ABS ABS_MT_POSITION_X 100 |
* EV_ABS ABS_MT_POSITION_Y 80 |
* EV_SYN SYN_REPORT 0 | SYN_DROPPED
* ------------------------ |
* EV_ABS ABS_MT_TRACKING_ID -1 |
* EV_SYN SYN_REPORT 0 |
* ------------------------ | ------------------------
* EV_ABS ABS_MT_SLOT 1 | EV_ABS ABS_MT_SLOT 1
* EV_ABS ABS_MT_POSITION_X 90 | EV_ABS ABS_MT_POSITION_X 90
* EV_ABS ABS_MT_POSITION_Y 10 | EV_ABS ABS_MT_POSITION_Y 10
* EV_SYN SYN_REPORT 0 | EV_SYN SYN_REPORT 0
* @endcode
* If such an event sequence occurs, libevdev will send all updated axes
* during the sync process. Axis events may thus be generated for devices
* without a currently valid `ABS_MT_TRACKING_ID`. Specifically for the above
* example, the client would receive the following event sequence:
* @code
* EV_ABS ABS_MT_SLOT 0 ← LIBEVDEV_READ_FLAG_NORMAL
* EV_ABS ABS_MT_TRACKING_ID -1
* EV_SYN SYN_REPORT 0
* ------------------------
* EV_SYN SYN_DROPPED 0 → LIBEVDEV_READ_STATUS_SYNC
* ------------------------
* EV_ABS ABS_MT_POSITION_X 100 ← LIBEVDEV_READ_FLAG_SYNC
* EV_ABS ABS_MT_POSITION_Y 80
* EV_SYN SYN_REPORT 0
* ----------------------------- → -EGAIN
* EV_ABS ABS_MT_SLOT 1 ← LIBEVDEV_READ_FLAG_NORMAL
* EV_ABS ABS_MT_POSITION_X 90
* EV_ABS ABS_MT_POSITION_Y 10
* EV_SYN SYN_REPORT 0
* -------------------
* @endcode
* The axis events do not reflect the position of a current touch point, a
* client must take care not to generate a new touch point based on those
* updates.
*
* Discarding events before synchronizing
* =====================================
*
* The kernel implements the client buffer as a ring buffer. `SYN_DROPPED`
* events are handled when the buffer is full and a new event is received
* from a device. All existing events are discarded, a `SYN_DROPPED` is added
* to the buffer followed by the actual device event. Further events will be
* appended to the buffer until it is either read by the client, or filled
* again, at which point the sequence repeats.
*
* When the client reads the buffer, the buffer will thus always consist of
* exactly one `SYN_DROPPED` event followed by an unspecified number of real
* events. The data the ioctls return is the current state of the device,
* i.e. the state after all these events have been processed. For example,
* assume the buffer contains the following sequence:
*
* @code
* EV_SYN SYN_DROPPED
* EV_ABS ABS_X 1
* EV_SYN SYN_REPORT 0
* EV_ABS ABS_X 2
* EV_SYN SYN_REPORT 0
* EV_ABS ABS_X 3
* EV_SYN SYN_REPORT 0
* EV_ABS ABS_X 4
* EV_SYN SYN_REPORT 0
* EV_ABS ABS_X 5
* EV_SYN SYN_REPORT 0
* EV_ABS ABS_X 6
* EV_SYN SYN_REPORT 0
* @endcode
* An ioctl at any time in this sequence will return a value of 6 for ABS_X.
*
* libevdev discards all events after a `SYN_DROPPED` to ensure the events
* during @ref LIBEVDEV_READ_FLAG_SYNC represent the last known state of the
* device. This loses some granularity of the events especially as the time
* between the `SYN_DROPPED` and the sync process increases. It does however
* avoid spurious cursor movements. In the above example, the event sequence
* by libevdev is:
* @code
* EV_SYN SYN_DROPPED
* EV_ABS ABS_X 6
* EV_SYN SYN_REPORT 0
* @endcode
*/
/**
* @page backwardscompatibility Compatibility and Behavior across kernel versions
*
* This page describes libevdev's behavior when the build-time kernel and the
* run-time kernel differ in their feature set.
*
* With the exception of event names, libevdev defines features that may be
* missing on older kernels and building on such kernels will not disable
* features. Running libevdev on a kernel that is missing some feature will
* change libevdev's behavior. In most cases, the new behavior should be
* obvious, but it is spelled out below in detail.
*
* Minimum requirements
* ====================
* libevdev requires a 2.6.36 kernel as minimum. Specifically, it requires
* kernel-support for `ABS_MT_SLOT`.
*
* Event and input property names
* ==============================
* Event names and input property names are defined at build-time by the
* linux/input.h shipped with libevdev.
* The list of event names is compiled at build-time, any events not defined
* at build time will not resolve. Specifically,
* libevdev_event_code_get_name() for an undefined type or code will
* always return `NULL`. Likewise, libevdev_property_get_name() will return NULL
* for properties undefined at build-time.
*
* Input properties
* ================
* If the kernel does not support input properties, specifically the
* `EVIOCGPROPS` ioctl, libevdev does not expose input properties to the caller.
* Specifically, libevdev_has_property() will always return 0 unless the
* property has been manually set with libevdev_enable_property().
*
* This also applies to the libevdev-uinput code. If uinput does not honor
* `UI_SET_PROPBIT`, libevdev will continue without setting the properties on
* the device.
*
* MT slot behavior
* =================
* If the kernel does not support the `EVIOCGMTSLOTS` ioctl, libevdev
* assumes all values in all slots are 0 and continues without an error.
*
* SYN_DROPPED behavior
* ====================
* A kernel without `SYN_DROPPED` won't send such an event. libevdev_next_event()
* will never require the switch to sync mode.
*/
/**
* @page ioctls evdev ioctls
*
* This page lists the status of the evdev-specific ioctls in libevdev.
*
* <dl>
* <dt>EVIOCGVERSION:</dt>
* <dd>supported, see libevdev_get_driver_version()</dd>
* <dt>EVIOCGID:</dt>
* <dd>supported, see libevdev_get_id_product(), libevdev_get_id_vendor(),
* libevdev_get_id_bustype(), libevdev_get_id_version()</dd>
* <dt>EVIOCGREP:</dt>
* <dd>supported, see libevdev_get_event_value())</dd>
* <dt>EVIOCSREP:</dt>
* <dd>supported, see libevdev_enable_event_code()</dd>
* <dt>EVIOCGKEYCODE:</dt>
* <dd>currently not supported</dd>
* <dt>EVIOCSKEYCODE:</dt>
* <dd>currently not supported</dd>
* <dt>EVIOCGKEYCODE_V2:</dt>
* <dd>currently not supported</dd>
* <dt>EVIOCSKEYCODE_V2:</dt>
* <dd>currently not supported</dd>
* <dt>EVIOCGNAME:</dt>
* <dd>supported, see libevdev_get_name()</dd>
* <dt>EVIOCGPHYS:</dt>
* <dd>supported, see libevdev_get_phys()</dd>
* <dt>EVIOCGUNIQ:</dt>
* <dd>supported, see libevdev_get_uniq()</dd>
* <dt>EVIOCGPROP:</dt>
* <dd>supported, see libevdev_has_property()</dd>
* <dt>EVIOCGMTSLOTS:</dt>
* <dd>supported, see libevdev_get_num_slots(), libevdev_get_slot_value()</dd>
* <dt>EVIOCGKEY:</dt>
* <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value()</dd>
* <dt>EVIOCGLED:</dt>
* <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value()</dd>
* <dt>EVIOCGSND:</dt>
* <dd>currently not supported</dd>
* <dt>EVIOCGSW:</dt>
* <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value()</dd>
* <dt>EVIOCGBIT:</dt>
* <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value()</dd>
* <dt>EVIOCGABS:</dt>
* <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value(),
* libevdev_get_abs_info()</dd>
* <dt>EVIOCSABS:</dt>
* <dd>supported, see libevdev_kernel_set_abs_info()</dd>
* <dt>EVIOCSFF:</dt>
* <dd>currently not supported</dd>
* <dt>EVIOCRMFF:</dt>
* <dd>currently not supported</dd>
* <dt>EVIOCGEFFECTS:</dt>
* <dd>currently not supported</dd>
* <dt>EVIOCGRAB:</dt>
* <dd>supported, see libevdev_grab()</dd>
* <dt>EVIOCSCLOCKID:</dt>
* <dd>supported, see libevdev_set_clock_id()</dd>
* <dt>EVIOCREVOKE:</dt>
* <dd>currently not supported, see
* http://lists.freedesktop.org/archives/input-tools/2014-January/000688.html</dd>
* <dt>EVIOCGMASK:</dt>
* <dd>currently not supported</dd>
* <dt>EVIOCSMASK:</dt>
* <dd>currently not supported</dd>
* </dl>
*
*/
/**
* @page kernel_header Kernel header
*
* libevdev provides its own copy of the Linux kernel header file and
* compiles against the definitions define here. Event type and event code
* names, etc. are taken from the file below:
* @include linux/input.h
*/
/**
* @page static_linking Statically linking libevdev
*
* Statically linking libevdev.a is not recommended. Symbol visibility is
* difficult to control in a static library, so extra care must be taken to
* only use symbols that are explicitly exported. libevdev's API stability
* guarantee only applies to those symbols.
*
* If you do link libevdev statically, note that in addition to the exported
* symbols, libevdev reserves the <b>_libevdev_*</b> namespace. Do not use
* or create symbols with that prefix, they are subject to change at any
* time.
*/
/**
* @page testing libevdev-internal test suite
*
* libevdev's internal test suite uses the
* [Check unit testing framework](http://check.sourceforge.net/). Tests are
* divided into test suites and test cases. Most tests create a uinput device,
* so you'll need to run as root, and your kernel must have
* `CONFIG_INPUT_UINPUT` enabled.
*
* 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. The test suite tries to detect
* if it is running inside gdb and disable forking. If that doesn't work for
* some reason, 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
*
*/
/**
* @defgroup init Initialization and setup
*
* Initialization, initial setup and file descriptor handling.
* These functions are the main entry points for users of libevdev, usually a
* caller will use this series of calls:
*
* @code
* struct libevdev *dev;
* int err;
*
* dev = libevdev_new();
* if (!dev)
* return ENOMEM;
*
* err = libevdev_set_fd(dev, fd);
* if (err < 0)
* printf("Failed (errno %d): %s\n", -err, strerror(-err));
*
* libevdev_free(dev);
* @endcode
*
* libevdev_set_fd() is the central call and initializes the internal structs
* for the device at the given fd. libevdev functions will fail if called
* before libevdev_set_fd() unless documented otherwise.
*/
/**
* @defgroup logging Library logging facilities
*
* libevdev provides two methods of logging library-internal messages. The
* old method is to provide a global log handler in
* libevdev_set_log_function(). The new method is to provide a per-context
* log handler in libevdev_set_device_log_function(). Developers are encouraged
* to use the per-context logging facilities over the global log handler as
* it provides access to the libevdev instance that caused a message, and is
* more flexible when libevdev is used from within a shared library.
*
* If a caller sets both the global log handler and a per-context log
* handler, each device with a per-context log handler will only invoke that
* log handler.
*
* @note To set a context-specific log handler, a context is needed.
* Thus developers are discouraged from using libevdev_new_from_fd() as
* important messages from the device initialization process may get lost.
*
* @note A context-specific handler cannot be used for libevdev's uinput
* devices. @ref uinput must use the global log handler.
*/
/**
* @defgroup bits Querying device capabilities
*
* Abstraction functions to handle device capabilities, specifically
* device properties such as the name of the device and the bits
* representing the events supported by this device.
*
* The logical state returned may lag behind the physical state of the device.
* libevdev queries the device state on libevdev_set_fd() and then relies on
* the caller to parse events through libevdev_next_event(). If a caller does not
* use libevdev_next_event(), libevdev will not update the internal state of the
* device and thus returns outdated values.
*/
/**
* @defgroup mt Multi-touch related functions
* Functions for querying multi-touch-related capabilities. MT devices
* following the kernel protocol B (using `ABS_MT_SLOT`) provide multiple touch
* points through so-called slots on the same axis. The slots are enumerated,
* a client reading from the device will first get an ABS_MT_SLOT event, then
* the values of axes changed in this slot. Multiple slots may be provided in
* before an `EV_SYN` event.
*
* As with @ref bits, the logical state of the device as seen by the library
* depends on the caller using libevdev_next_event().
*
* The Linux kernel requires all axes on a device to have a semantic
* meaning, matching the axis names in linux/input.h. Some devices merely
* export a number of axes beyond the available axis list. For those
* devices, the multitouch information is invalid. Specifically, if a device
* provides the `ABS_MT_SLOT` axis AND also the `ABS_RESERVED` axis, the
* device is not treated as multitouch device. No slot information is
* available and the `ABS_MT` axis range for these devices is treated as all
* other `EV_ABS` axes.
*
* Note that because of limitations in the kernel API, such fake multitouch
* devices can not be reliably synced after a `SYN_DROPPED` event. libevdev
* ignores all `ABS_MT` axis values during the sync process and instead
* relies on the device to send the current axis value with the first event
* after `SYN_DROPPED`.
*/
/**
* @defgroup kernel Modifying the appearance or capabilities of the device
*
* Modifying the set of events reported by this device. By default, the
* libevdev device mirrors the kernel device, enabling only those bits
* exported by the kernel. This set of functions enable or disable bits as
* seen from the caller.
*
* Enabling an event type or code does not affect event reporting - a
* software-enabled event will not be generated by the physical hardware.
* Disabling an event will prevent libevdev from routing such events to the
* caller. Enabling and disabling event types and codes is at the library
* level and thus only affects the caller.
*
* If an event type or code is enabled at kernel-level, future users of this
* device will see this event enabled. Currently there is no option of
* disabling an event type or code at kernel-level.
*/
/**
* @defgroup misc Miscellaneous helper functions
*
* Functions for printing or querying event ranges. The list of names is
* compiled into libevdev and is independent of the run-time kernel.
* Likewise, the max for each event type is compiled in and does not check
* the kernel at run-time.
*/
/**
* @defgroup events Event handling
*
* Functions to handle events and fetch the current state of the event.
* libevdev updates its internal state as the event is processed and forwarded
* to the caller. Thus, the libevdev state of the device should always be identical
* to the caller's state. It may however lag behind the actual state of the device.
*/
/**
* @ingroup init
*
* Opaque struct representing an evdev device.
*/
struct libevdev;
/**
* @ingroup events
*/
enum libevdev_read_flag {
LIBEVDEV_READ_FLAG_SYNC = 1, /**< Process data in sync mode */
LIBEVDEV_READ_FLAG_NORMAL = 2, /**< Process data in normal mode */
LIBEVDEV_READ_FLAG_FORCE_SYNC = 4, /**< Pretend the next event is a SYN_DROPPED and
require the caller to sync */
LIBEVDEV_READ_FLAG_BLOCKING = 8 /**< The fd is not in O_NONBLOCK and a read may block */
};
/**
* @ingroup init
*
* Initialize a new libevdev device. This function only allocates the
* required memory and initializes the struct to sane default values.
* To actually hook up the device to a kernel device, use
* libevdev_set_fd().
*
* Memory allocated through libevdev_new() must be released by the
* caller with libevdev_free().
*
* @see libevdev_set_fd
* @see libevdev_free
*/
struct libevdev *libevdev_new(void);
/**
* @ingroup init
*
* Initialize a new libevdev device from the given fd.
*
* This is a shortcut for
*
* @code
* int err;
* struct libevdev *dev = libevdev_new();
* err = libevdev_set_fd(dev, fd);
* @endcode
*
* @param fd A file descriptor to the device in O_RDWR or O_RDONLY mode.
* @param[out] dev The newly initialized evdev device.
*
* @return On success, 0 is returned and dev is set to the newly
* allocated struct. On failure, a negative errno is returned and the value
* of dev is undefined.
*
* @see libevdev_free
*/
int libevdev_new_from_fd(int fd, struct libevdev **dev);
/**
* @ingroup init
*
* Clean up and free the libevdev struct. After completion, the <code>struct
* libevdev</code> is invalid and must not be used.
*
* Note that calling libevdev_free() does not close the file descriptor
* currently associated with this instance.
*
* @param dev The evdev device
*
* @note This function may be called before libevdev_set_fd().
*/
void libevdev_free(struct libevdev *dev);
/**
* @ingroup logging
*/
enum libevdev_log_priority {
LIBEVDEV_LOG_ERROR = 10, /**< critical errors and application bugs */
LIBEVDEV_LOG_INFO = 20, /**< informational messages */
LIBEVDEV_LOG_DEBUG = 30 /**< debug information */
};
/**
* @ingroup logging
*
* Logging function called by library-internal logging.
* This function is expected to treat its input like printf would.
*
* @param priority Log priority of this message
* @param data User-supplied data pointer (see libevdev_set_log_function())
* @param file libevdev source code file generating this message
* @param line libevdev source code line generating this message
* @param func libevdev source code function generating this message
* @param format printf-style format string
* @param args List of arguments
*
* @see libevdev_set_log_function
*/
typedef void (*libevdev_log_func_t)(enum libevdev_log_priority priority,
void *data,
const char *file, int line,
const char *func,
const char *format, va_list args)
LIBEVDEV_ATTRIBUTE_PRINTF(6, 0);
/**
* @ingroup logging
*
* Set a printf-style logging handler for library-internal logging. The default
* logging function is to stdout.
*
* @note The global log handler is only called if no context-specific log
* handler has been set with libevdev_set_device_log_function().
*
* @param logfunc The logging function for this device. If NULL, the current
* logging function is unset and no logging is performed.
* @param data User-specific data passed to the log handler.
*
* @note This function may be called before libevdev_set_fd().
*
* @deprecated Use per-context logging instead, see
* libevdev_set_device_log_function().
*/
void libevdev_set_log_function(libevdev_log_func_t logfunc, void *data);
/**
* @ingroup logging
*
* Define the minimum level to be printed to the log handler.
* Messages higher than this level are printed, others are discarded. This
* is a global setting and applies to any future logging messages.
*
* @param priority Minimum priority to be printed to the log.
*
* @deprecated Use per-context logging instead, see
* libevdev_set_device_log_function().
*/
void libevdev_set_log_priority(enum libevdev_log_priority priority);
/**
* @ingroup logging
*
* Return the current log priority level. Messages higher than this level
* are printed, others are discarded. This is a global setting.
*
* @return the current log level
*
* @deprecated Use per-context logging instead, see
* libevdev_set_device_log_function().
*/
enum libevdev_log_priority libevdev_get_log_priority(void);
/**
* @ingroup logging
*
* Logging function called by library-internal logging for a specific
* libevdev context. This function is expected to treat its input like
* printf would.
*
* @param dev The evdev device
* @param priority Log priority of this message
* @param data User-supplied data pointer (see libevdev_set_log_function())
* @param file libevdev source code file generating this message
* @param line libevdev source code line generating this message
* @param func libevdev source code function generating this message
* @param format printf-style format string
* @param args List of arguments
*
* @see libevdev_set_log_function
* @since 1.3
*/
typedef void (*libevdev_device_log_func_t)(const struct libevdev *dev,
enum libevdev_log_priority priority,
void *data,
const char *file, int line,
const char *func,
const char *format, va_list args)
LIBEVDEV_ATTRIBUTE_PRINTF(7, 0);
/**
* @ingroup logging
*
* Set a printf-style logging handler for library-internal logging for this
* device context. The default logging function is NULL, i.e. the global log
* handler is invoked. If a context-specific log handler is set, the global
* log handler is not invoked for this device.
*
* @note This log function applies for this device context only, even if
* another context exists for the same fd.
*
* @param dev The evdev device
* @param logfunc The logging function for this device. If NULL, the current
* logging function is unset and logging falls back to the global log
* handler, if any.
* @param priority Minimum priority to be printed to the log.
* @param data User-specific data passed to the log handler.
*
* @note This function may be called before libevdev_set_fd().
* @since 1.3
*/
void libevdev_set_device_log_function(struct libevdev *dev,
libevdev_device_log_func_t logfunc,
enum libevdev_log_priority priority,
void *data);
/**
* @ingroup init
*/
enum libevdev_grab_mode {
LIBEVDEV_GRAB = 3, /**< Grab the device if not currently grabbed */
LIBEVDEV_UNGRAB = 4 /**< Ungrab the device if currently grabbed */
};
/**
* @ingroup init
*
* Grab or ungrab the device through a kernel EVIOCGRAB. This prevents other
* clients (including kernel-internal ones such as rfkill) from receiving
* events from this device.
*
* This is generally a bad idea. Don't do this.
*
* Grabbing an already grabbed device, or ungrabbing an ungrabbed device is
* a noop and always succeeds.
*
* A grab is an operation tied to a file descriptor, not a device. If a
* client changes the file descriptor with libevdev_change_fd(), it must
* also re-issue a grab with libevdev_grab().
*
* @param dev The evdev device, already initialized with libevdev_set_fd()
* @param grab If true, grab the device. Otherwise ungrab the device.
*
* @return 0 if the device was successfully grabbed or ungrabbed, or a
* negative errno in case of failure.
*/
int libevdev_grab(struct libevdev *dev, enum libevdev_grab_mode grab);
/**
* @ingroup init
*
* Set the fd for this struct and initialize internal data.
* The fd must be in O_RDONLY or O_RDWR mode.
*
* This function may only be called once per device. If the device changed and
* you need to re-read a device, use libevdev_free() and libevdev_new(). If
* you need to change the fd after closing and re-opening the same device, use
* libevdev_change_fd().