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

   1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: RC
   3
   4 .. _lirc-write:
   5
   6 ************
   7 LIRC write()
   8 ************
   9
  10 Name
  11 ====
  12
  13 lirc-write - Write to a LIRC device
  14
  15 Synopsis
  16 ========
  17
  18 .. code-block:: c
  19
  20     #include <unistd.h>
  21
  22 .. c:function:: ssize_t write( 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 with data to be written
  32
  33 ``count``
  34     Number of bytes at the buffer
  35
  36 Description
  37 ===========
  38
  39 :c:func:`write()` writes up to ``count`` bytes to the device
  40 referenced by the file descriptor ``fd`` from the buffer starting at
  41 ``buf``.
  42
  43 The exact format of the data depends on what mode a driver is in, use
  44 :ref:`lirc_get_features` to get the supported modes and use
  45 :ref:`lirc_set_send_mode` set the mode.
  46
  47 When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, the data written to
  48 the chardev is a pulse/space sequence of integer values. Pulses and spaces
  49 are only marked implicitly by their position. The data must start and end
  50 with a pulse, therefore, the data must always include an uneven number of
  51 samples. The write function blocks until the data has been transmitted
  52 by the hardware. If more data is provided than the hardware can send, the
  53 driver returns ``EINVAL``.
  54
  55 When in :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` mode, one
  56 ``struct lirc_scancode`` must be written to the chardev at a time, else
  57 ``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member,
  58 and the :ref:`IR protocol <Remote_controllers_Protocols>` in the
  59 :c:type:`rc_proto`: member. All other members must be
  60 set to 0, else ``EINVAL`` is returned. If there is no protocol encoder
  61 for the protocol or the scancode is not valid for the specified protocol,
  62 ``EINVAL`` is returned. The write function blocks until the scancode
  63 is transmitted by the hardware.
  64
  65 Return Value
  66 ============
  67
  68 On success, the number of bytes written is returned. It is not an error if
  69 this number is smaller than the number of bytes requested, or the amount
  70 of data required for one frame.  On error, -1 is returned, and the ``errno``
  71 variable is set appropriately. The generic error codes are described at the
  72 :ref:`Generic Error Codes <gen-errors>` chapter.