Documentation/media/uapi/rc/lirc-read.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _lirc-read:
  11
  12 ***********
  13 LIRC read()
  14 ***********
  15
  16 Name
  17 ====
  18
  19 lirc-read - Read from a LIRC device
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. code-block:: c
  26
  27     #include <unistd.h>
  28
  29
  30 .. c:function:: ssize_t read( int fd, void *buf, size_t count )
  31     :name: lirc-read
  32
  33
  34 Arguments
  35 =========
  36
  37 ``fd``
  38     File descriptor returned by ``open()``.
  39
  40 ``buf``
  41    Buffer to be filled
  42
  43 ``count``
  44    Max number of bytes to read
  45
  46 Description
  47 ===========
  48
  49 :ref:`read() <lirc-read>` attempts to read up to ``count`` bytes from file
  50 descriptor ``fd`` into the buffer starting at ``buf``.  If ``count`` is zero,
  51 :ref:`read() <lirc-read>` returns zero and has no other results. If ``count``
  52 is greater than ``SSIZE_MAX``, the result is unspecified.
  53
  54 The exact format of the data depends on what :ref:`lirc_modes` a driver
  55 uses. Use :ref:`lirc_get_features` to get the supported mode, and use
  56 :ref:`lirc_set_rec_mode` set the current active mode.
  57
  58 The mode :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` is for raw IR,
  59 in which packets containing an unsigned int value describing an IR signal are
  60 read from the chardev.
  61
  62 Alternatively, :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` can be available,
  63 in this mode scancodes which are either decoded by software decoders, or
  64 by hardware decoders. The :c:type:`rc_proto` member is set to the
  65 protocol used for transmission, and ``scancode`` to the decoded scancode,
  66 and the ``keycode`` set to the keycode or ``KEY_RESERVED``.
  67
  68
  69 Return Value
  70 ============
  71
  72 On success, the number of bytes read is returned. It is not an error if
  73 this number is smaller than the number of bytes requested, or the amount
  74 of data required for one frame.  On error, -1 is returned, and the ``errno``
  75 variable is set appropriately.