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/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _lirc-write:
11
12************
13LIRC write()
14************
15
16Name
17====
18
19lirc-write - Write to a LIRC device
20
21
22Synopsis
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
33Arguments
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
45Description
46===========
47
48:ref:`write() <lirc-write>` writes up to ``count`` bytes to the device
49referenced by the file descriptor ``fd`` from the buffer starting at
50``buf``.
51
52The 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
56When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, the data written to
57the chardev is a pulse/space sequence of integer values. Pulses and spaces
58are only marked implicitly by their position. The data must start and end
59with a pulse, therefore, the data must always include an uneven number of
60samples. The write function blocks until the data has been transmitted
61by the hardware. If more data is provided than the hardware can send, the
62driver returns ``EINVAL``.
63
64When 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,
67and the :ref:`IR protocol <Remote_controllers_Protocols>` in the
68:c:type:`rc_proto`: member. All other members must be
69set to 0, else ``EINVAL`` is returned. If there is no protocol encoder
70for the protocol or the scancode is not valid for the specified protocol,
71``EINVAL`` is returned. The write function blocks until the scancode
72is transmitted by the hardware.
73
74
75Return Value
76============
77
78On success, the number of bytes written is returned. It is not an error if
79this number is smaller than the number of bytes requested, or the amount
80of data required for one frame.  On error, -1 is returned, and the ``errno``
81variable is set appropriately. The generic error codes are described at the
82:ref:`Generic Error Codes <gen-errors>` chapter.
83