diff options
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | Makefile.am | 2 | ||||
-rw-r--r-- | configure.ac | 11 | ||||
-rw-r--r-- | man/Makefile.am | 33 | ||||
-rw-r--r-- | man/libevdev_enable_event_type.txt | 63 | ||||
-rw-r--r-- | man/libevdev_get_abs_min.txt | 59 | ||||
-rw-r--r-- | man/libevdev_get_name.txt | 49 | ||||
-rw-r--r-- | man/libevdev_get_num_slots.txt | 53 | ||||
-rw-r--r-- | man/libevdev_grab.txt | 51 | ||||
-rw-r--r-- | man/libevdev_has_event_type.txt | 69 | ||||
-rw-r--r-- | man/libevdev_new.txt | 72 | ||||
-rw-r--r-- | man/libevdev_next_event.txt | 81 | ||||
-rw-r--r-- | man/libevdev_set_fd.txt | 67 | ||||
-rw-r--r-- | man/libevdev_set_log_handler.txt | 43 |
14 files changed, 653 insertions, 1 deletions
@@ -44,3 +44,4 @@ ylwrap *.swp .vimdir *.tar.* +*.3 diff --git a/Makefile.am b/Makefile.am index 83f98e5..78958e6 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ -SUBDIRS = libevdev test +SUBDIRS = libevdev test man pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = libevdev.pc diff --git a/configure.ac b/configure.ac index f3607b8..83c9e37 100644 --- a/configure.ac +++ b/configure.ac @@ -40,8 +40,19 @@ if test "x$GCC" = "xyes"; then fi AC_SUBST(GCC_CFLAGS) +AC_PATH_PROG(ASCIIDOC, [a2x]) +if test "x$ASCIIDOC" = "x"; then + AC_MSG_WARN([asciidoc not found - unable to build man pages]) + have_asciidoc=no +else + have_asciidoc=yes +fi +AM_CONDITIONAL([HAVE_ASCIIDOC], [test "$have_asciidoc" = yes]) + + AC_CONFIG_FILES([Makefile libevdev/Makefile + man/Makefile test/Makefile libevdev.pc]) AC_OUTPUT diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..13fcede --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,33 @@ + +# find all libevdev_*.3 pages +# for this to work, the man pages must be created before the man target, so +# we hook into all-local (see below) +dist_man3_MANS = $(shell find . -name "libevdev_*.3" -printf "%P\n") + +man_src = \ + libevdev_enable_event_type.txt \ + libevdev_get_abs_min.txt \ + libevdev_get_name.txt \ + libevdev_get_num_slots.txt \ + libevdev_grab.txt \ + libevdev_has_event_type.txt \ + libevdev_new.txt \ + libevdev_next_event.txt \ + libevdev_set_fd.txt \ + libevdev_set_log_handler.txt + +if HAVE_ASCIIDOC + +.txt.3: + a2x --doctype manpage --format manpage $< + +all-local: $(man_src) $(man_src:.txt=.3) + +SUFFIXES = .3 .txt + +endif + +EXTRA_DIST = $(man_src) + +clean-local: + rm -f *.3 diff --git a/man/libevdev_enable_event_type.txt b/man/libevdev_enable_event_type.txt new file mode 100644 index 0000000..37db111 --- /dev/null +++ b/man/libevdev_enable_event_type.txt @@ -0,0 +1,63 @@ +libevdev_disable_event_type(3) +============================== + +NAME +---- + +libevdev_disable_event_type, libevdev_disable_event_code, libevdev_enable_event_type, libevdev_enable_event_code - disable or enable an event type or code on the device + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +int libevdev_disable_event_type(struct libevdev *dev, unsigned int type); + +int libevdev_enable_event_type(struct libevdev *dev, unsigned int type); + +int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigned int code); + +int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigned int code, const void *data); + +DESCRIPTION +----------- + +*libevdev_disable_event_type* and *libevdev_disable_event_code* disable +capabilities on this device. Once an event type or +code is disabled, future calls to *libevdev_has_event_type* and +*libevdev_has_event_code* will return 0. + +*libevev_enable_event_type* and *libevdev_enable_event_code* enable +capabilities on this device. Once an event type or code is enabled, future +calls to *libevdev_has_event_type* and *libevdev_has_event_code* will return 1. + +This change is library-internal only. Neither function disables the actual +axis on the device and other processes using libevdev to read from the +device will not see any changes. + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. + +*type*:: + Specifies the event type to enable or disable. + +*code*:: + Specifies the event code to enable or disable. + +*data*:: + If type is EV_ABS, data points to a struct input_absinfo with the + ranges for this axis. Otherwise, 'data' is ignored. + +RETURN VALUE +------------ +On success, these functions return 0. On failure, these functions return -1. + +Failure indicates an invalid argument that is out of range from the kernel +parameters. + +SEE ALSO +-------- + +libevdev_has_event_type(3), libevdev_has_event_code(3) diff --git a/man/libevdev_get_abs_min.txt b/man/libevdev_get_abs_min.txt new file mode 100644 index 0000000..3d087e9 --- /dev/null +++ b/man/libevdev_get_abs_min.txt @@ -0,0 +1,59 @@ +libevdev_get_abs_min(3) +======================= + +NAME +---- + +libevdev_get_abs_min, libevdev_get_abs_max, libevdev_get_abs_fuzz, libevdev_get_abs_flat, libevdev_get_abs_resolution, libevdev_get_abs_info - get information about an absolut axis on this device + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, unsigned int code); + +int libevdev_get_abs_min(const struct libevdev *dev, unsigned int code); + +int libevdev_get_abs_max(const struct libevdev *dev, unsigned int code); + +int libevdev_get_abs_fuzz(const struct libevdev *dev, unsigned int code); + +int libevdev_get_abs_flat(const struct libevdev *dev, unsigned int code); + +int libevdev_get_abs_resolution(const struct libevdev *dev, unsigned int code); + +DESCRIPTION +----------- +*libevdev_get_abs_info* returns the struct input_absinfo describing the axis +on this device. This struct contains the axis ranges for the given axis. + +*libevdev_get_abs_min*, *libevdev_get_abs_max*, *libevdev_get_abs_fuzz*, *libevdev_get_abs_flat*, +*libevdev_get_abs_resolution* are convenience functions that return the +respective field from the struct input_absinfo for the given axis. + +The caller must check if the axis is supported by the device first using +*libevdev_has_event_code(3)*. + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. +*code*:: + Axis code, ranging from ABS_X to ABS_MAX. + +RETURN VALUE +------------ +On success, *libevdev_get_abs_info* returns a pointer to the struct +input_absinfo. If the axis does not exist on the device or the axis code is +invalid, NULL is returned. + +On success, *libevdev_get_abs_min*, *libevdev_get_abs_max*, *libevdev_get_abs_fuzz*, *libevdev_get_abs_flat*, +*libevdev_get_abs_resolution* return the respective value for this axis. +If the axis does not exist on the device or the axis code is invalid, the +return value is undefined. + +SEE ALSO +-------- + +libevdev_has_event_type(3), libevdev_has_event_code(3) diff --git a/man/libevdev_get_name.txt b/man/libevdev_get_name.txt new file mode 100644 index 0000000..9b274dc --- /dev/null +++ b/man/libevdev_get_name.txt @@ -0,0 +1,49 @@ +libevdev_get_name(3) +==================== + +NAME +---- + +libevdev_get_name, libevdev_get_product_id, libevdev_get_vendor_id, libevdev_get_bustype - retreive information about this device + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +const char* libevdev_get_name(const struct libevdev *dev); + +int libevdev_get_product_id(const struct libevdev *dev); + +int libevdev_get_vendor_id(const struct libevdev *dev); + +int libevdev_get_bustype(const struct libevdev *dev); + +DESCRIPTION +----------- + +*libevdev_get_name* returns a pointer to the device name as set by the +kernel. + +*libevdev_get_product_id* and *libevdev_get_vendor_id* return the numeric +product and vendor ID as set by the kernel. + +*libevdev_get_bustype* returns the numeric bus type as set by the kernel. + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. + +RETURN VALUE +------------ +*libevdev_get_name* returns a const pointer to the device name. + +*libevdev_get_product_id*, *libevdev_get_vendor_id* and +*libevdev_get_bustype* return the numeric product ID, vendor ID, or bus +type. + +SEE ALSO +-------- + +libevdev_has_event_type(3), libevdev_has_event_code(3) diff --git a/man/libevdev_get_num_slots.txt b/man/libevdev_get_num_slots.txt new file mode 100644 index 0000000..ee5bf90 --- /dev/null +++ b/man/libevdev_get_num_slots.txt @@ -0,0 +1,53 @@ +libevdev_get_num_slots(3) +========================= + +NAME +---- + +libevdev_get_num_slots, libevdev_get_current_slot - get the number of available multitouch slots and the currently active slot + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +int libevdev_get_num_slots(const struct libevdev *dev); + +int libevdev_get_current_slot(const struct libevdev *dev); + +DESCRIPTION +----------- +*libevdev_get_num_slots* returns the available number of multitouch slots on +this device. + +*libevdev_get_current_slot* returns the currently active slot. Note that +this value may lag behind the state visible to other readers on the +same device. The return value of this function is the current slot as seen +by the caller, i.e. the state as defined by the set of events processed so +far. + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. + +RETURN VALUE +------------ +On success, *libevdev_get_num_slots* returns the number of slots. If the +device does not support the slot protocol, -1 is returned. + +On success, *libevdev_get_current_slot* returns the current of slot ID. If +the device does not support the slot protocol, the return value is +undefined. + +NOTES +----- +Some devices support more touch points that they expose multitouch slots +for. For example, a touchpad may only expose two slots, but detect up to +four-finger touches. A caller should check for BTN_TOOL_TRIPLETAP, +BTN_TOOL_QUADTAP, etc. as well as the state of the slots. + +SEE ALSO +-------- + +libevdev_has_event_type(3), libevdev_has_event_code(3), libevdev_get_slot_value(3) diff --git a/man/libevdev_grab.txt b/man/libevdev_grab.txt new file mode 100644 index 0000000..3081286 --- /dev/null +++ b/man/libevdev_grab.txt @@ -0,0 +1,51 @@ +libevdev_grab(3) +================ + +NAME +---- + +libevdev_grab - grab the kernel device and become its exclusive user. + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +enum EvdevGrabModes { + LIBEVDEV_GRAB, + LIBEVDEV_UNGRAB, +}; + +int libevdev_grab(struct libevdev *dev, int grab); + + +DESCRIPTION +----------- + +*libevdev_grab* performs an *EVIOCGRAB* on the kernel device, making this +process the exclusive recipient of events from that device. This disrupts +event delivery to other processes including in-kernel consumers of these +events such as *rfkill(1)*. It is usually a bad idea to use this function. + +An attempt to grab or ungrab a device already grabbed or currently not +grabbed device will be ignored and returns success. + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. + +*grab*:: + To grab the device, use LIBEVDEV_GRAB. + To ungrab the device, use LIBEVDEV_UNGRAB. + +RETURN VALUE +------------ + +On success, *libevdev_grab* returns zero. On failure, a negative errno is +returned. + +*EINVAL*:: + An invalid grab mode was specified. + +For a full list of potential error codes consult *ioctl(2)*. diff --git a/man/libevdev_has_event_type.txt b/man/libevdev_has_event_type.txt new file mode 100644 index 0000000..b651b97 --- /dev/null +++ b/man/libevdev_has_event_type.txt @@ -0,0 +1,69 @@ +libevdev_has_event_type(3) +========================== + +NAME +---- + +libevdev_has_event_type, libevdev_has_event_code, libevdev_has_property - check if a event type, code or property is available on this device + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +int libevdev_has_event_type(const struct libevdev *dev, unsigned int type); + +int libevdev_has_event_code(const struct libevdev *dev, unsigned int type, unsigned int code); + +int libevdev_has_property(const struct libevdev *dev, unsigned int prop); + +DESCRIPTION +----------- + +*libevdev_has_event_type* and *libevdev_has_event_code* check if an event +type or event code is supported by this device. + +Event types are listed in <linux/input.h> and start with EV_SYN and end with +EV_MAX. Event types signal general availability of a type of event, i.e. +they indicate if a device has keys/buttons, axes, LEDs etc. Event codes are +specific to each event type and are also listed in <linux/input.h>. Event +codes signal the device's ability to send a specific key/button, axis, LED, +etc. event. + +*libevdev_has_property* checks if a property bit is set on this device. +Property values are listed in <linux/input.h> and start with +INPUT_PROP_POINTER and end with INPUT_PROP_MAX. + + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. + +*type*:: + Specifies the event type to query. + +*code*:: + Specifies the event code to query. + +*prop*:: + Specifies the property to query. + +RETURN VALUE +------------ + +If the device supports a given type, code or property, +*libevdev_has_event_type*, *libevdev_has_event_code* and +*libevdev_has_property* return 1. Otherwise, 0 is returned. + +NOTES +----- +An event type or code only signals the potential for the device to send +such events. Many devices initialize more axes than they physically provide +and such axes will never generate an event. + +SEE ALSO +-------- + +libevdev_enable_event_type(3), libevdev_enable_event_code(3), +libevdev_disable_event_type(3), libevdev_disable_event_code(3) diff --git a/man/libevdev_new.txt b/man/libevdev_new.txt new file mode 100644 index 0000000..b1f0d6e --- /dev/null +++ b/man/libevdev_new.txt @@ -0,0 +1,72 @@ +libevdev_new(3) +=============== + +NAME +---- + +libevdev_new, libevdev_new_from_fd, libevdev_free - initialize and free a libevdev device + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +struct libevdev* libevdev_new(void); + +int libevdev_new_from_fd(int fd, struct libevdev **dev); + +void libevdev_free(struct libevdev *dev); + +DESCRIPTION +----------- + +*libevdev_new* allocates the memory required for libevdev's +wrapping of an evdev kernel input device. This does not initialize the +device yet, use *libevdev_set_fd(3)* for that. + +*libevdev_new_from_fd* allocates the memory required for a kernel input +device and initializes that device from the given fd. The fd must be opened +in read or read-write mode and the caller must have the required permissions +to perform *ioctl(2)* calls on the fd. + +The function *libevdev_free* frees the memory associated with the kernel input +device. + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. In *libevdev_new_from_fd*, 'dev' is + set to the newly allocated pointer. In *libevdev_free*, 'dev' is the + previously allocated struct. + +*fd*:: + An open file descriptor to the kernel device. The fd must be opened + in O_RDONLY or O_RDWR. + +RETURN VALUE +------------ + +On success, *libevdev_new* returns a pointer to the opaque 'struct +libevdev'. On failure, NULL is returned. + +On success, *libevdev_new_from_fd* returns 0 and sets 'dev' to the newly +allocated device. On failure, a negative errno is returned indicating the +type of failure: + +*ENOSP*:: + Memory allocation failed. + +*EBADF*:: + 'fd' is not a valid file descriptor. + +*EACCESS*:: + Permission denied. + +For a full list of potential error codes consult *ioctl(2)*. + +SEE ALSO +-------- + +libevdev_set_fd(3), libevdev_change_fd(3), +libevdev_grab(3), +libevdev_has_event_type(3), libevdev_has_event_code(3) diff --git a/man/libevdev_next_event.txt b/man/libevdev_next_event.txt new file mode 100644 index 0000000..677de78 --- /dev/null +++ b/man/libevdev_next_event.txt @@ -0,0 +1,81 @@ +libevdev_next_event(3) +====================== + +NAME +---- + +libevdev_next_event - fetch the next event from the device + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +enum EvdevReadFlags { + LIBEVDEV_READ_SYNC, +}; + +int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_event *ev); + +DESCRIPTION +----------- + +*libevdev_next_event* returns the next event available for this device. This +event may have been read previously and is currently in libevdev's event +queue, or the event may be read off the fd now. + +A device has two read modes: normal and sync mode. In normal mode, the next +available event is returned. If the event is a SYN_DROPPED event, +*libevdev_next_event* returns 1 and switches to sync mode. + +In sync mode, the caller must repeatedly call *libevdev_next_event* with the +'LIBEVDEV_READ_SYNC' flag set. *libevdev_next_event* returns the set of +events required to bring the caller's device state in sync with the actual +device. If no more events are available, *libevdev_next_event* returns +-EAGAIN and the caller can switch back to normal mode. + +If the caller does not call with the 'LIBEVDEV_READ_SYNC' flag once in sync +mode, libevdev drops all events and returns the next event from the device. + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. + +*flags*:: + Specifies the read mode for this device. + +*ev*:: + The event returned. + +RETURN VALUE +------------ + +On success, *libevdev_next_event* returns 0 and 'ev' points to the next +event available on the device. + +If a SYN_DROPPED event was read from the device, *libevdev_next_event* +returns 1 and switches to sync mode. The value of 'ev' is undefined. + +On error, *libevdev_next_event* returns a negative errno and the value of +'ev' is undefined. + +*ENODEV*:: + The file descriptor does not point to a valid device. Call + *libevdev_set_fd(3)* first. + +*EAGAIN*:: + No events are currently available for this device. + +For a full list of potential error codes consult *read(2)*. + +NOTES +----- +*libevdev_next_event* reads more than one event off the fd. If the fd is not +set to O_NONBLOCK, this call will block if no more events are available on +the fd, even if events are present in the queue. + +SEE ALSO +-------- + +libevdev_set_fd(3) diff --git a/man/libevdev_set_fd.txt b/man/libevdev_set_fd.txt new file mode 100644 index 0000000..bd4cd15 --- /dev/null +++ b/man/libevdev_set_fd.txt @@ -0,0 +1,67 @@ +libevdev_set_fd(3) +================== + +NAME +---- + +libevdev_set_fd, libevdev_change_fd, libevdev_get_fd - set or change the fd for this device. + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +int libevdev_set_fd(struct libevdev* dev, int fd); + +int libevdev_change_fd(struct libevdev* dev, int fd); + +int libevdev_get_fd(const struct libevdev* dev); + + +DESCRIPTION +----------- + +*libevdev_set_fd* initializes the fd for this device, querying the kernel +device for information. The fd must be open in O_RDONLY or O_RDWR mode. This +call must be performed before querying the device for any information. + +*libevdev_change_fd* changes the fd for this device without querying the +kernel for information. Use this function if the original fd had to be +closed and re-opened without the device changing underneath. + +*libevdev_get_fd* returns the current fd for this device. + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. + +*fd*:: + The fd to use for this device. + +RETURN VALUE +------------ + +On success, *libevdev_set_fd* returns 0. On error, a negative errno is +returned. For a full list of potential error codes consult *ioctl(2)*. + +On success, *libevdev_change_fd* returns 0. On error, it returns -1. + +*libevdev_get_fd* returns the currently set file descriptor, or -1 if none +has been set yet. + +NOTES +----- +*libevdev_set_fd* may only be called once per device. If the device needs to +be re-initialized, use *libevdev_free(3)* and *libevdev_new(3)*. + +If the device was initialized with *libevdev_new_from_fd(3)*, +*libevdev_set_fd* was already called by the library and calling it again +will result in an error. + +*libevdev_get_fd* may be called before *libevdev_set_fd*. + +SEE ALSO +-------- + +libevdev_new(3), libevdev_free(3), libevdev_new_from_fd(3) diff --git a/man/libevdev_set_log_handler.txt b/man/libevdev_set_log_handler.txt new file mode 100644 index 0000000..2d7153e --- /dev/null +++ b/man/libevdev_set_log_handler.txt @@ -0,0 +1,43 @@ +libevdev_set_log_handler(3) +=========================== + +NAME +---- + +libevdev_set_log_handler - set the library's log handler to a user-supplied function + +SYNOPSIS +-------- + +#include <libevdev/libevdev.h> + +typedef void (*libevdev_log_func_t)(const char *format, va_list args); + +void libevdev_set_log_handler(struct libevdev *dev, libevdev_log_func_t logfunc); + + +DESCRIPTION +----------- + +*libevdev_set_log_handler* set the log handler for the given device to the +user-specified function. Messages from the library will printed using this +function. + +PARAMETERS +---------- +*dev*:: + Pointer to the libevdev device. + +*logfunc*:: + A vprintf-style function. + +Notes +----- + +This function may be called before *libevdev_set_fd*. + + +SEE ALSO +-------- + +libevdev_set_fd(3) |