Add man-pages for the current interface

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

.gitignore

@@ -44,3 +44,4 @@ ylwrap
 *.swp
 .vimdir
 *.tar.*
+*.3

Makefile.am

@@ -1,4 +1,4 @@
-SUBDIRS = libevdev test
+SUBDIRS = libevdev test man
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = libevdev.pc

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

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

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)

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)

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)

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)

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)*.

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)

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)

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)

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)

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)