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