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