1.. SPDX-License-Identifier: GPL-2.0
2
3.. _GPIO_GET_LINEEVENT_IOCTL:
4
5************************
6GPIO_GET_LINEEVENT_IOCTL
7************************
8
9.. warning::
10    This ioctl is part of chardev_v1.rst and is obsoleted by
11    gpio-v2-get-line-ioctl.rst.
12
13Name
14====
15
16GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the kernel.
17
18Synopsis
19========
20
21.. c:macro:: GPIO_GET_LINEEVENT_IOCTL
22
23``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_request *request)``
24
25Arguments
26=========
27
28``chip_fd``
29    The file descriptor of the GPIO character device returned by `open()`.
30
31``request``
32    The :c:type:`event_request<gpioevent_request>` specifying the line
33    to request and its configuration.
34
35Description
36===========
37
38Request a line with edge detection from the kernel.
39
40On success, the requesting process is granted exclusive access to the line
41value and may receive events when edges are detected on the line, as
42described in gpio-lineevent-data-read.rst.
43
44The state of a line is guaranteed to remain as requested until the returned
45file descriptor is closed. Once the file descriptor is closed, the state of
46the line becomes uncontrolled from the userspace perspective, and may revert
47to its default state.
48
49Requesting a line already in use is an error (**EBUSY**).
50
51Requesting edge detection on a line that does not support interrupts is an
52error (**ENXIO**).
53
54As with the :ref:`line handle<gpio-get-linehandle-config-support>`, the
55bias configuration is best effort.
56
57Closing the ``chip_fd`` has no effect on existing line events.
58
59Configuration Rules
60-------------------
61
62The following configuration rules apply:
63
64The line event is requested as an input, so no flags specific to output lines,
65``GPIOHANDLE_REQUEST_OUTPUT``, ``GPIOHANDLE_REQUEST_OPEN_DRAIN``, or
66``GPIOHANDLE_REQUEST_OPEN_SOURCE``, may be set.
67
68Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set.
69If no bias flags are set then the bias configuration is not changed.
70
71The edge flags, ``GPIOEVENT_REQUEST_RISING_EDGE`` and
72``GPIOEVENT_REQUEST_FALLING_EDGE``, may be combined to detect both rising
73and falling edges.
74
75Requesting an invalid configuration is an error (**EINVAL**).
76
77Return Value
78============
79
80On success 0 and the :c:type:`request.fd<gpioevent_request>` contains the file
81descriptor for the request.
82
83On error -1 and the ``errno`` variable is set appropriately.
84Common error codes are described in error-codes.rst.
85