Section (4) lirc
lirc — lirc devices
devices provide a low-level bidirectional interface to
infra-red (IR) remotes. Most of these devices can receive,
and some can send. When receiving or sending data, the driver
works in two different modes depending on the underlying
Some hardware (typically TV-cards) decodes the IR signal
internally and provides decoded button presses as scancode
values. Drivers for this kind of hardware work in
LIRC_MODE_SCANCODE mode. Such
hardware usually does not support sending IR signals.
Furthermore, such hardware can only decode a limited set of
IR protocols, usually only the protocol of the specific
remote which is bundled with, for example, a TV-card.
Other hardware provides a stream of pulse/space durations.
Such drivers work in
LIRC_MODE_MODE2 mode. Sometimes, this kind
of hardware also supports sending IR data. Such hardware can
be used with (almost) any kind of remote. This type of
hardware can also be used in
LIRC_MODE_SCANCODE mode, in which case the
kernel IR decoders will decode the IR. These decoders can be
written in extended BPF (see bpf(2)) and attached to the
(see below) allows probing for whether receiving and sending
is supported, and in which modes, amongst other features.
Reading input with the LIRC_MODE_MODE2 mode
In the LIRC_MODE_MODE2 mode, the data returned by read(2) provides 32-bit values representing a space or a pulse duration. The time of the duration (microseconds) is encoded in the lower 24 bits. The upper 8 bits indicate the type of package:
Value reflects a space duration (microseconds).
Value reflects a pulse duration (microseconds).
Value reflects a frequency (Hz); see the
Value reflects a space duration (microseconds). The package reflects a timeout; see the
Reading input with the LIRC_MODE_SCANCODE mode
mode, the data returned by read(2) reflects decoded
button presses, in the struct
lirc_scancode. The scancode is stored in
scancode field, and the
IR protocol is stored in
rc_proto. This field has one the values
of the enum
Writing output with the LIRC_MODE_PULSE mode
The data written to the character device using write(2) is a pulse/space sequence of integer values. Pulses and spaces are only marked implicitly by their position. The data must start and end with a pulse, thus it must always include an odd number of samples. The write(2) function blocks until the data has been transmitted by the hardware. If more data is provided than the hardware can send, the write(2) call fails with the error EINVAL.
Writing output with the LIRC_MODE_SCANCODE mode
The data written to the character devices must be a
rc_proto fields must filled in, all other
fields must be 0. The kernel IR encoders will convert the
scancode to pulses and spaces. The protocol or scancode is
invalid, or the
The LIRC device_zsingle_quotesz_s ioctl definition is bound by the ioctl function definition of struct file_operations, leaving us with an unsigned int for the ioctl command and an unsigned long for the argument. For the purposes of ioctl portability across 32-bit and 64-bit architectures, these values are capped to their 32-bit sizes.
#include <linux/lirc.h> /* But see BUGS */ int ioctl(int fd, int cmd, ...);
The following ioctls can be used to probe or change
settings. Many require a third argument, usually an
int. referred to below as
Always Supported Commands
/dev/lirc* devices always
support the following commands:
Returns a bit mask of combined features bits; see FEATURES.
If a device returns an error code for
LIRC_GET_FEATURES, it is safe to assume
it is not a
lirc devices support
the commands listed below. Unless otherwise stated, these
fail with the error ENOTTY
if the operation isn_zsingle_quotesz_t supported, or with the error
EINVAL if the operation
failed, or invalid arguments were provided. If a driver
does not announce support of certain features, invoking the
corresponding ioctls will fail with the error ENOTTY.
lircdevice has no receiver, this operation fails with the error ENOTTY. Otherwise, it returns the receive mode, which will be one of:
The driver returns a sequence of pulse/space durations.
The driver returns struct
lirc_scancodevalues, each of which represents a decoded button press.
Set the receive mode.
LIRC_MODE_MODE2. If the
lircdevice has no receiver, this operation fails with the error
Return the send mode.
LIRC_MODE_SCANCODEis supported. If the
lircdevice cannot send, this operation fails with the error
Set the send mode.
LIRC_MODE_PULSE. If the
lircdevice cannot send, this operation fails with the error ENOTTY.
Set the modulation frequency. The argument is the frequency (Hz).
Set the carrier duty cycle.
valis a number in the range [0,100] which describes the pulse width as a percentage of the total cycle. Currently, no special meaning is defined for 0 or 100, but the values are reserved for future use.
Some devices have internal timers that can be used to detect when there has been no IR activity for a long time. This can help lircd(8) in detecting that an IR signal is finished and can speed up the decoding process. These operations return integer values with the minimum/maximum timeout that can be set (microseconds). Some devices have a fixed timeout. For such drivers,
LIRC_GET_MAX_TIMEOUTwill fail with the error ENOTTY.
Set the integer value for IR inactivity timeout (microseconds). To be accepted, the value must be within the limits defined by
LIRC_GET_MAX_TIMEOUT. A value of 0 (if supported by the hardware) disables all hardware timeouts and data should be reported as soon as possible. If the exact value cannot be set, then the next possible value
greaterthan the given value should be set.
Return the current inactivity timeout (microseconds). Available since Linux 4.18.
valis 1) or disable (
valis 0) timeout packages in
LIRC_MODE_MODE2. The behavior of this operation has varied across kernel versions:
Since Linux 4.16: each time the lirc device is opened, timeout reports are by default enabled for the resulting file descriptor. The
LIRC_SET_REC_TIMEOUToperation can be used to disable (and, if desired, to later re-enable) the timeout on the file descriptor.
In Linux 4.15 and earlier: timeout reports are disabled by default, and enabling them (via
LIRC_SET_REC_TIMEOUT) on any file descriptor associated with the
lircdevice has the effect of enabling timeouts for all file descriptors referring to that device (until timeouts are disabled again).
Set the upper bound of the receive carrier frequency (Hz). See
Sets the lower bound of the receive carrier frequency (Hz). For this to take affect, first set the lower bound using the
LIRC_SET_REC_CARRIER_RANGEioctl, and then the upper bound using the
valis 1) or disable (
valis 0) the measure mode. If enabled, from the next key press on, the driver will send
LIRC_MODE2_FREQUENCYpackets. By default, this should be turned off.
Return the driver resolution (microseconds).
Enable the set of transmitters specified in
val, which contains a bit mask where each enabled transmitter is a 1. The first transmitter is encoded by the least significant bit, and so on. When an invalid bit mask is given, for example a bit is set even though the device does not have so many transmitters, this operation returns the number of available transmitters and does nothing otherwise.
Some devices are equipped with a special wide band receiver which is intended to be used to learn the output of an existing remote. This ioctl can be used to enable (
valequals 1) or disable (
valequals 0) this functionality. This might be useful for devices that otherwise have narrow band receivers that prevent them to be used with certain remotes. Wide band receivers may also be more precise. On the other hand, their disadvantage usually is reduced range of reception.
Wide band receiver may be implicitly enabled if you enable carrier reports. In that case, it will be disabled as soon as you disable carrier reports. Trying to disable a wide band receiver while carrier reports are active will do nothing.
returns a bit mask describing features of the driver. The
following bits may be returned in the mask:
The driver is capable of receiving using
The driver is capable of receiving using
The driver supports changing the modulation frequency using
The driver supports changing the duty cycle using
The driver supports changing the active transmitter(s) using
The driver supports setting the receive carrier frequency using
lircdevice since the drivers were merged in kernel release 2.6.36 must have
LIRC_CAN_SET_REC_CARRIERfeature is set.
The driver supports
LIRC_SET_REC_CARRIER_RANGE. The lower bound of the carrier must first be set using the
LIRC_SET_REC_CARRIER_RANGEioctl, before using the
LIRC_SET_REC_CARRIERioctl to set the upper bound.
The driver supports
The driver supports
The driver supports measuring of the modulation frequency using
The driver supports learning mode using
The driver supports sending using
Using these devices requires the kernel source header file
lirc.h. This file is not
available before kernel release 4.6. Users of older kernels
could use the file bundled in http://www.lirc.org
ir-ctl(1), lircd(8), bpf(2)
This page is part of release 5.04 of the Linux
man-pages project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
Copyright (c) 2015-2016, Alec Leamas
Copyright (c) 2018, Sean Young <seanmess.org>
This is free documentation; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
The GNU General Public License_zsingle_quotesz_s references to object code
and executables are to be interpreted as the output of any
document formatting or typesetting system, including
intermediate and printed output.
This manual is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public
License along with this manual; if not, see