1.. SPDX-License-Identifier: GPL-2.0 2 3.. _GPIO_LINEINFO_CHANGED_READ: 4 5************************** 6GPIO_LINEINFO_CHANGED_READ 7************************** 8 9.. warning:: 10 This ioctl is part of chardev_v1.rst and is obsoleted by 11 gpio-v2-lineinfo-changed-read.rst. 12 13Name 14==== 15 16GPIO_LINEINFO_CHANGED_READ - Read line info change events for watched lines 17from the chip. 18 19Synopsis 20======== 21 22``int read(int chip_fd, void *buf, size_t count)`` 23 24Arguments 25========= 26 27``chip_fd`` 28 The file descriptor of the GPIO character device returned by `open()`. 29 30``buf`` 31 The buffer to contain the :c:type:`events<gpioline_info_changed>`. 32 33``count`` 34 The number of bytes available in ``buf``, which must be at least the size 35 of a :c:type:`gpioline_info_changed` event. 36 37Description 38=========== 39 40Read line info change events for watched lines from the chip. 41 42.. note:: 43 Monitoring line info changes is not generally required, and would typically 44 only be performed by a system monitoring component. 45 46 These events relate to changes in a line's request state or configuration, 47 not its value. Use gpio-lineevent-data-read.rst to receive events when a 48 line changes value. 49 50A line must be watched using gpio-get-lineinfo-watch-ioctl.rst to generate 51info changed events. Subsequently, a request, release, or reconfiguration 52of the line will generate an info changed event. 53 54The kernel timestamps events when they occur and stores them in a buffer 55from where they can be read by userspace at its convenience using `read()`. 56 57The size of the kernel event buffer is fixed at 32 events per ``chip_fd``. 58 59The buffer may overflow if bursts of events occur quicker than they are read 60by userspace. If an overflow occurs then the most recent event is discarded. 61Overflow cannot be detected from userspace. 62 63Events read from the buffer are always in the same order that they were 64detected by the kernel, including when multiple lines are being monitored by 65the one ``chip_fd``. 66 67To minimize the number of calls required to copy events from the kernel to 68userspace, `read()` supports copying multiple events. The number of events 69copied is the lower of the number available in the kernel buffer and the 70number that will fit in the userspace buffer (``buf``). 71 72A `read()` will block if no event is available and the ``chip_fd`` has not 73been set **O_NONBLOCK**. 74 75The presence of an event can be tested for by checking that the ``chip_fd`` is 76readable using `poll()` or an equivalent. 77 78First added in 5.7. 79 80Return Value 81============ 82 83On success the number of bytes read, which will be a multiple of the size of 84a :c:type:`gpioline_info_changed` event. 85 86On error -1 and the ``errno`` variable is set appropriately. 87Common error codes are described in error-codes.rst. 88