lirc(4)

💖 lirc(4) 💖

okay bestie, welcome to the Kernel Interfaces Manual page for lirc. this is the low-level IR remote lore, and it's giving very serious kernel energy. no cap. let's get into it 💅

✨ NAME ✨

• lirc — lirc devices

🌸 DESCRIPTION 🌸

okay so the /dev/lirc* character devices are your low-level bidirectional interface to infra-red (IR) remotes. most of these devices can receive, and some can send. when they're receiving or sending data, the driver works in two different modes depending on the underlying hardware. it's literally hardware-dependent, bestie.

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. not very main character of it, but okay.

Other hardware provides a stream of pulse/space durations. Such drivers work in LIRC_MODE_MODE2 mode. 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 lirc device. Sometimes, this kind of hardware also supports sending IR data. highkey iconic.

The LIRC_GET_FEATURES ioctl (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. Pulse (also known as flash) indicates a duration of infrared light being detected, and space (also known as gap) indicates a duration with no infrared. If the duration of space exceeds the inactivity timeout, a special timeout package is delivered, which marks the end of a message. The upper 8 bits indicate the type of package:

• LIRC_MODE2_SPACE — Value reflects a space duration (microseconds).
• LIRC_MODE2_PULSE — Value reflects a pulse duration (microseconds).
• LIRC_MODE2_FREQUENCY — Value reflects a frequency (Hz); see the LIRC_SET_MEASURE_CARRIER_MODE ioctl.
• LIRC_MODE2_TIMEOUT — Value reflects a space duration (microseconds). The package reflects a timeout; see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.
• LIRC_MODE2_OVERFLOW — The IR receiver encountered an overflow, and as a result data is missing (since Linux 5.18).

🎀 Reading input with the LIRC_MODE_SCANCODE mode 🎀

In the LIRC_MODE_SCANCODE mode, the data returned by read(2) reflects decoded button presses, in the struct lirc_scancode. The scancode is stored in the scancode field, and the IR protocol is stored in rc_proto. This field has one the values of the enum rc_proto.

✨ 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. periodt.

💫 Writing output with the LIRC_MODE_SCANCODE mode 💫

The data written to the character devices must be a single struct lirc_scancode. The scancode and rc_proto fields must be 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 lirc device cannot transmit.

👑 IOCTL COMMANDS 👑

#include <linux/lirc.h>    /* But see BUGS */

int ioctl(int fd, int cmd, int *val);

The following ioctl(2) operations are provided by the lirc character device to probe or change specific lirc hardware settings. let's go.

💅 Always Supported Commands 💅

/dev/lirc* devices always support the following commands:

• LIRC_GET_FEATURES (void) — 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 device. so if it's giving errors, it's not lirc, bestie.

🌈 Optional Commands 🌈

Some lirc devices support the commands listed below. Unless otherwise stated, these fail with the error ENOTTY if the operation isn'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. the vibe check is: if it's not announced, it's not happening.

• LIRC_GET_REC_MODE (void) — If the lirc device has no receiver, this operation fails with the error ENOTTY. Otherwise, it returns the receive mode, which will be one of:
  • LIRC_MODE_MODE2 — The driver returns a sequence of pulse/space durations.
  • LIRC_MODE_SCANCODE — The driver returns struct lirc_scancode values, each of which represents a decoded button press.
• LIRC_SET_REC_MODE (int) — Set the receive mode. val is either LIRC_MODE_SCANCODE or LIRC_MODE_MODE2. If the lirc device has no receiver, this operation fails with the error ENOTTY.
• LIRC_GET_SEND_MODE (void) — Return the send mode. LIRC_MODE_PULSE or LIRC_MODE_SCANCODE is supported. If the lirc device cannot send, this operation fails with the error ENOTTY.
• LIRC_SET_SEND_MODE (int) — Set the send mode. val is either LIRC_MODE_SCANCODE or LIRC_MODE_PULSE. If the lirc device cannot send, this operation fails with the error ENOTTY.
• LIRC_SET_SEND_CARRIER (int) — Set the modulation frequency. The argument is the frequency (Hz).
• LIRC_SET_SEND_DUTY_CYCLE (int) — Set the carrier duty cycle. val is 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. so 0 and 100 are just sitting there, reserved. periodt.
• LIRC_GET_MIN_TIMEOUT(void), LIRC_GET_MAX_TIMEOUT(void) — 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_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT will fail with the error ENOTTY.
• LIRC_SET_REC_TIMEOUT (int) — Set the integer value for IR inactivity timeout (microseconds). To be accepted, the value must be within the limits defined by LIRC_GET_MIN_TIMEOUT and 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 greater than the given value should be set.
• LIRC_GET_REC_TIMEOUT (void) — Return the current inactivity timeout (microseconds). Available since Linux 4.18.
• LIRC_SET_REC_TIMEOUT_REPORTS (int) — Enable (val is 1) or disable (val is 0) timeout packages in LIRC_MODE_MODE2. The behavior of this operation has varied across kernel versions:
  • Since Linux 5.17: timeout packages are always enabled and this ioctl is a no-op.
  • Since Linux 4.16: timeout packages are enabled by default. Each time the lirc device is opened, the LIRC_SET_REC_TIMEOUT operation 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 packages are disabled by default, and enabling them (via LIRC_SET_REC_TIMEOUT) on any file descriptor associated with the lirc device has the effect of enabling timeouts for all file descriptors referring to that device (until timeouts are disabled again). the lore is deep, bestie.
• LIRC_SET_REC_CARRIER (int) — Set the upper bound of the receive carrier frequency (Hz). See LIRC_SET_REC_CARRIER_RANGE.
• LIRC_SET_REC_CARRIER_RANGE (int) — 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_RANGE ioctl, and then the upper bound using the LIRC_SET_REC_CARRIER ioctl. order matters, bestie.
• LIRC_SET_MEASURE_CARRIER_MODE (int) — Enable (val is 1) or disable (val is 0) the measure mode. If enabled, from the next key press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default, this should be turned off.
• LIRC_GET_REC_RESOLUTION (void) — Return the driver resolution (microseconds).
• LIRC_SET_TRANSMITTER_MASK (int) — 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.
• LIRC_SET_WIDEBAND_RECEIVER (int) — 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 (val equals 1) or disable (val equals 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.

Note: 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.

✨ FEATURES ✨

okay bestie so the LIRC_GET_FEATURES ioctl hands you back a bit mask that tells you what the driver can actually do — like its little resume of skills. And the following bits may show up in that mask: 👇

• LIRC_CAN_REC_MODE2 — this driver can receive stuff using LIRC_MODE_MODE2.
• LIRC_CAN_REC_SCANCODE — this driver can receive using LIRC_MODE_SCANCODE.
• LIRC_CAN_SET_SEND_CARRIER — you can change the modulation frequency with LIRC_SET_SEND_CARRIER. slay.
• LIRC_CAN_SET_SEND_DUTY_CYCLE — you can change the duty cycle with LIRC_SET_SEND_DUTY_CYCLE.
• LIRC_CAN_SET_TRANSMITTER_MASK — you can change which transmitter(s) are active with LIRC_SET_TRANSMITTER_MASK.
• LIRC_CAN_SET_REC_CARRIER — you can set the receive carrier frequency with LIRC_SET_REC_CARRIER. but wait, there's lore: any lirc device since the drivers got merged in Linux 2.6.36 must also have LIRC_CAN_SET_REC_CARRIER_RANGE set if this LIRC_CAN_SET_REC_CARRIER feature is set. it's giving package deal 💅
• LIRC_CAN_SET_REC_CARRIER_RANGE — the driver supports LIRC_SET_REC_CARRIER_RANGE. order matters here, bestie: you gotta set the lower bound first using the LIRC_SET_REC_CARRIER_RANGE ioctl, and only then use the LIRC_SET_REC_CARRIER ioctl to set the upper bound.
• LIRC_CAN_GET_REC_RESOLUTION — the driver supports LIRC_GET_REC_RESOLUTION.
• LIRC_CAN_SET_REC_TIMEOUT — the driver supports LIRC_SET_REC_TIMEOUT.
• LIRC_CAN_MEASURE_CARRIER — the driver can measure the modulation frequency, using LIRC_SET_MEASURE_CARRIER_MODE.
• LIRC_CAN_USE_WIDEBAND_RECEIVER — the driver supports learning mode via LIRC_SET_WIDEBAND_RECEIVER. iconic behavior fr fr.
• LIRC_CAN_SEND_PULSE — the driver can send using LIRC_MODE_PULSE or LIRC_MODE_SCANCODE.

---

🫠 BUGS 🫠

okay so this is the one (1) annoying thing, don't shoot the messenger: using these devices requires the kernel source header file lirc.h. And that file? literally not available before Linux 4.6. 😭

if you're on an older kernel, the move is to use the file that's bundled over at http://www.lirc.org. that's it, that's the workaround, you're welcome 🎀

---

👀 SEE ALSO 👀

• ir-ctl(1)
• lircd(8)
• bpf(2)
• https://www.kernel.org/doc/html/latest/userspace-api/media/rc/lirc-dev.html

---

and that's a wrap on the whole page, bestie!! 🌈 this little masterpiece lives in Linux man-pages 6.20, and she was stamped with the date 2026-02-08. go forth and ir-ctl responsibly 💅✨🦋