Documentation/userspace-api/media/rc/lirc-read.rst

   1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: RC
   3
   4 .. _lirc-read:
   5
   6 ***********
   7 LIRC read()
   8 ***********
   9
  10 Name
  11 ====
  12
  13 lirc-read - Read from a LIRC device
  14
  15 Synopsis
  16 ========
  17
  18 .. code-block:: c
  19
  20     #include <unistd.h>
  21
  22 .. c:function:: ssize_t read( int fd, void *buf, size_t count )
  23
  24 Arguments
  25 =========
  26
  27 ``fd``
  28     File descriptor returned by ``open()``.
  29
  30 ``buf``
  31    Buffer to be filled
  32
  33 ``count``
  34    Max number of bytes to read
  35
  36 Description
  37 ===========
  38
  39 :c:func:`read()` attempts to read up to ``count`` bytes from file
  40 descriptor ``fd`` into the buffer starting at ``buf``.  If ``count`` is zero,
  41 :c:func:`read()` returns zero and has no other results. If ``count``
  42 is greater than ``SSIZE_MAX``, the result is unspecified.
  43
  44 The exact format of the data depends on what :ref:`lirc_modes` a driver
  45 uses. Use :ref:`lirc_get_features` to get the supported mode, and use
  46 :ref:`lirc_set_rec_mode` set the current active mode.
  47
  48 The mode :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` is for raw IR,
  49 in which packets containing an unsigned int value describing an IR signal are
  50 read from the chardev.
  51
  52 Alternatively, :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` can be available,
  53 in this mode scancodes which are either decoded by software decoders, or
  54 by hardware decoders. The :c:type:`rc_proto` member is set to the
  55 :ref:`IR protocol <Remote_controllers_Protocols>`
  56 used for transmission, and ``scancode`` to the decoded scancode,
  57 and the ``keycode`` set to the keycode or ``KEY_RESERVED``.
  58
  59 Return Value
  60 ============
  61
  62 On success, the number of bytes read is returned. It is not an error if
  63 this number is smaller than the number of bytes requested, or the amount
  64 of data required for one frame.  On error, -1 is returned, and the ``errno``
  65 variable is set appropriately.