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

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