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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _lirc-write:
   4
   5 ************
   6 LIRC write()
   7 ************
   8
   9 Name
  10 ====
  11
  12 lirc-write - Write to 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 write( int fd, void *buf, size_t count )
  24     :name: lirc-write
  25
  26 Arguments
  27 =========
  28
  29 ``fd``
  30     File descriptor returned by ``open()``.
  31
  32 ``buf``
  33     Buffer with data to be written
  34
  35 ``count``
  36     Number of bytes at the buffer
  37
  38 Description
  39 ===========
  40
  41 :ref:`write() <lirc-write>` writes up to ``count`` bytes to the device
  42 referenced by the file descriptor ``fd`` from the buffer starting at
  43 ``buf``.
  44
  45 The exact format of the data depends on what mode a driver is in, use
  46 :ref:`lirc_get_features` to get the supported modes and use
  47 :ref:`lirc_set_send_mode` set the mode.
  48
  49 When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, the data written to
  50 the chardev is a pulse/space sequence of integer values. Pulses and spaces
  51 are only marked implicitly by their position. The data must start and end
  52 with a pulse, therefore, the data must always include an uneven number of
  53 samples. The write function blocks until the data has been transmitted
  54 by the hardware. If more data is provided than the hardware can send, the
  55 driver returns ``EINVAL``.
  56
  57 When in :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` mode, one
  58 ``struct lirc_scancode`` must be written to the chardev at a time, else
  59 ``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member,
  60 and the protocol in the :c:type:`rc_proto`: member. All other members must be
  61 set to 0, else ``EINVAL`` is returned. If there is no protocol encoder
  62 for the protocol or the scancode is not valid for the specified protocol,
  63 ``EINVAL`` is returned. The write function blocks until the scancode
  64 is transmitted by the hardware.
  65
  66
  67 Return Value
  68 ============
  69
  70 On success, the number of bytes written is returned. It is not an error if
  71 this number is smaller than the number of bytes requested, or the amount
  72 of data required for one frame.  On error, -1 is returned, and the ``errno``
  73 variable is set appropriately. The generic error codes are described at the
  74 :ref:`Generic Error Codes <gen-errors>` chapter.