malloc.3: Clarify that realloc() may move the memory block
[man-pages.git] / man4 / lirc.4
blob8bc8a95cf50d01c72ce111efd5a255d8883184ae
1 .\" Copyright (c) 2015-2016, Alec Leamas
2 .\" Copyright (c) 2018, Sean Young <sean@mess.org>
3 .\"
4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
5 .\" This is free documentation; you can redistribute it and/or
6 .\" modify it under the terms of the GNU General Public License as
7 .\" published by the Free Software Foundation; either version 2 of
8 .\" the License, or (at your option) any later version.
9 .\"
10 .\" The GNU General Public License's references to "object code"
11 .\" and "executables" are to be interpreted as the output of any
12 .\" document formatting or typesetting system, including
13 .\" intermediate and printed output.
14 .\"
15 .\" This manual is distributed in the hope that it will be useful,
16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 .\" GNU General Public License for more details.
19 .\"
20 .\" You should have received a copy of the GNU General Public
21 .\" License along with this manual; if not, see
22 .\" <http://www.gnu.org/licenses/>.
23 .\" %%%LICENSE_END
24 .TH LIRC 4 2019-03-06 "Linux" "Linux Programmer's Manual"
25 .SH NAME
26 lirc \- lirc devices
27 .SH DESCRIPTION
28 The
29 .I /dev/lirc*
30 character devices provide a low-level
31 bidirectional interface to infra-red (IR) remotes.
32 Most of these devices can receive, and some can send.
33 When receiving or sending data, the driver works in two different modes
34 depending on the underlying hardware.
35 .PP
36 Some hardware (typically TV-cards) decodes the IR signal internally
37 and provides decoded button presses as scancode values.
38 Drivers for this kind of hardware work in
39 .BR LIRC_MODE_SCANCODE
40 mode.
41 Such hardware usually does not support sending IR signals.
42 Furthermore, such hardware can only decode a limited set of IR protocols,
43 usually only the protocol of the specific remote which is
44 bundled with, for example, a TV-card.
45 .PP
46 Other hardware provides a stream of pulse/space durations.
47 Such drivers work in
48 .BR LIRC_MODE_MODE2
49 mode.
50 Sometimes, this kind of hardware also supports
51 sending IR data.
52 Such hardware can be used with (almost) any kind of remote.
53 This type of hardware can also be used in
54 .BR LIRC_MODE_SCANCODE
55 mode, in which case the kernel IR decoders will decode the IR.
56 These decoders can be written in extended BPF (see
57 .BR bpf (2))
58 and attached to the
59 .B lirc
60 device.
61 .PP
62 The \fBLIRC_GET_FEATURES\fR ioctl (see below) allows probing for whether
63 receiving and sending is supported, and in which modes, amongst other
64 features.
65 .\"
66 .SS Reading input with the LIRC_MODE_MODE2 mode
67 In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by
68 .BR read (2)
69 provides 32-bit values representing a space or a pulse duration.
70 The time of the duration (microseconds) is encoded in the lower 24 bits.
71 The upper 8 bits indicate the type of package:
72 .TP 4
73 .BR LIRC_MODE2_SPACE
74 Value reflects a space duration (microseconds).
75 .TP 4
76 .BR LIRC_MODE2_PULSE
77 Value reflects a pulse duration (microseconds).
78 .TP 4
79 .BR LIRC_MODE2_FREQUENCY
80 Value reflects a frequency (Hz); see the
81 .B LIRC_SET_MEASURE_CARRIER_MODE
82 ioctl.
83 .TP 4
84 .BR LIRC_MODE2_TIMEOUT
85 Value reflects a space duration (microseconds).
86 The package reflects a timeout; see the
87 .B LIRC_SET_REC_TIMEOUT_REPORTS
88 ioctl.
89 .\"
90 .SS Reading input with the LIRC_MODE_SCANCODE mode
91 In the \fBLIRC_MODE_SCANCODE\fR
92 mode, the data returned by
93 .BR read (2)
94 reflects decoded button presses, in the struct \fIlirc_scancode\fR.
95 The scancode is stored in the \fIscancode\fR field, and the IR protocol
96 is stored in \fIrc_proto\fR.
97 This field has one the values of the \fIenum rc_proto\fR.
98 .\"
99 .SS Writing output with the LIRC_MODE_PULSE mode
100 The data written to the character device using
101 .BR write (2)
102 is a pulse/space sequence of integer values.
103 Pulses and spaces are only marked implicitly by their position.
104 The data must start and end with a pulse, thus it must always include
105 an odd number of samples.
107 .BR write (2)
108 function blocks until the data has been transmitted by the
109 hardware.
110 If more data is provided than the hardware can send, the
111 .BR write (2)
112 call fails with the error
113 .BR EINVAL .
114 .SS Writing output with the LIRC_MODE_SCANCODE mode
115 The data written to the character devices must be a single struct
116 \fIlirc_scancode\fR.
117 The \fIscancode\fR and \fIrc_proto\fR fields must
118 filled in, all other fields must be 0.
119 The kernel IR encoders will
120 convert the scancode to pulses and spaces.
121 The protocol or scancode is invalid, or the
122 .B lirc
123 device cannot transmit.
124 .SH IOCTL COMMANDS
125 The LIRC device's ioctl definition is bound by the ioctl function
126 definition of
127 .IR "struct file_operations" ,
128 leaving us with an
129 .IR "unsigned int"
130 for the ioctl command and an
131 .IR "unsigned long"
132 for the argument.
133 For the purposes of ioctl portability across 32-bit and 64-bit architectures,
134 these values are capped to their 32-bit sizes.
137 #include <linux/lirc.h>    /* But see BUGS */
138 int ioctl(int fd, int cmd, ...);
141 The following ioctls can be used to probe or change specific
142 .B lirc
143 hardware settings.
144 Many require a third argument, usually an
145 .IR int ,
146 referred to below as
147 .IR val .
149 .SS Always Supported Commands
150 \fI/dev/lirc*\fR devices always support the following commands:
151 .TP 4
152 .BR LIRC_GET_FEATURES " (\fIvoid\fP)"
153 Returns a bit mask of combined features bits; see FEATURES.
155 If a device returns an error code for
156 .BR LIRC_GET_FEATURES ,
157 it is safe to assume it is not a
158 .B lirc
159 device.
161 .SS Optional Commands
162 Some
163 .B lirc
164 devices support the commands listed below.
165 Unless otherwise stated, these fail with the error \fBENOTTY\fR if the
166 operation isn't supported, or with the error \fBEINVAL\fR if the operation
167 failed, or invalid arguments were provided.
168 If a driver does not announce support of certain features, invoking
169 the corresponding ioctls will fail with the error
170 .BR ENOTTY .
172 .BR LIRC_GET_REC_MODE " (\fIvoid\fP)"
173 If the
174 .B lirc
175 device has no receiver, this operation fails with the error
176 .BR ENOTTY .
177 Otherwise, it returns the receive mode, which will be one of:
180 .BR LIRC_MODE_MODE2
181 The driver returns a sequence of pulse/space durations.
183 .BR LIRC_MODE_SCANCODE
184 The driver returns struct
185 .I lirc_scancode
186 values, each of which represents
187 a decoded button press.
190 .BR LIRC_SET_REC_MODE " (\fIint\fP)"
191 Set the receive mode.
192 .IR val
193 is either
194 .BR LIRC_MODE_SCANCODE
196 .BR LIRC_MODE_MODE2 .
197 If the
198 .B lirc
199 device has no receiver, this operation fails with the error
200 .B ENOTTY.
202 .BR LIRC_GET_SEND_MODE " (\fIvoid\fP)"
203 Return the send mode.
204 .BR LIRC_MODE_PULSE
206 .BR LIRC_MODE_SCANCODE
207 is supported.
208 If the
209 .B lirc
210 device cannot send, this operation fails with the error
211 .B ENOTTY.
213 .BR LIRC_SET_SEND_MODE " (\fIint\fP)"
214 Set the send mode.
215 .IR val
216 is either
217 .BR LIRC_MODE_SCANCODE
219 .BR LIRC_MODE_PULSE .
220 If the
221 .B lirc
222 device cannot send, this operation fails with the error
223 .BR ENOTTY .
225 .BR LIRC_SET_SEND_CARRIER " (\fIint\fP)"
226 Set the modulation frequency.
227 The argument is the frequency (Hz).
229 .BR LIRC_SET_SEND_DUTY_CYCLE " (\fIint\fP)"
230 Set the carrier duty cycle.
231 .I val
232 is a number in the range [0,100] which
233 describes the pulse width as a percentage of the total cycle.
234 Currently, no special meaning is defined for 0 or 100, but the values
235 are reserved for future use.
238 .BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\
239 LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
240 Some devices have internal timers that can be used to detect when
241 there has been no IR activity for a long time.
242 This can help
243 .BR lircd (8)
244 in detecting that an IR signal is finished and can speed up the
245 decoding process.
246 These operations
247 return integer values with the minimum/maximum timeout that can be
248 set (microseconds).
249 Some devices have a fixed timeout.
250 For such drivers,
251 .BR LIRC_GET_MIN_TIMEOUT
253 .BR LIRC_GET_MAX_TIMEOUT
254 will fail with the error
255 .BR ENOTTY .
257 .BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)"
258 Set the integer value for IR inactivity timeout (microseconds).
259 To be accepted, the value must be within the limits defined by
260 .BR LIRC_GET_MIN_TIMEOUT
262 .BR LIRC_GET_MAX_TIMEOUT .
263 A value of 0 (if supported by the hardware) disables all hardware
264 timeouts and data should be reported as soon as possible.
265 If the exact value cannot be set, then the next possible value
266 .I greater
267 than the given value should be set.
269 .BR LIRC_GET_REC_TIMEOUT " (\fIvoid\fP)"
270 Return the current inactivity timeout (microseconds).
271 Available since Linux 4.18.
273 .BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
274 Enable
275 .RI ( val
276 is 1) or disable
277 .RI ( val
278 is 0) timeout packages in
279 .BR LIRC_MODE_MODE2 .
280 The behavior of this operation has varied across kernel versions:
282 .IP * 3
283 Since Linux 4.16: each time the
284 .B lirc device is opened,
285 timeout reports are by default enabled for the resulting file descriptor.
287 .B LIRC_SET_REC_TIMEOUT
288 operation can be used to disable (and, if desired, to later re-enable)
289 the timeout on the file descriptor.
290 .IP *
291 In Linux 4.15 and earlier:
292 timeout reports are disabled by default, and enabling them (via
293 .BR LIRC_SET_REC_TIMEOUT )
294 on any file descriptor associated with the
295 .B lirc
296 device has the effect of enabling timeouts for all file descriptors
297 referring to that device (until timeouts are disabled again).
300 .BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
301 Set the upper bound of the receive carrier frequency (Hz).
303 .BR LIRC_SET_REC_CARRIER_RANGE .
305 .BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
306 Sets the lower bound of the receive carrier frequency (Hz).
307 For this to take affect, first set the lower bound using the
308 .BR LIRC_SET_REC_CARRIER_RANGE
309 ioctl, and then the upper bound using the
310 .BR LIRC_SET_REC_CARRIER
311 ioctl.
313 .BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)"
314 Enable
315 .RI ( val
316 is 1) or disable
317 .RI ( val
318 is 0) the measure mode.
319 If enabled, from the next key press on, the driver will send
320 .BR LIRC_MODE2_FREQUENCY
321 packets.
322 By default, this should be turned off.
324 .BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
325 Return the driver resolution (microseconds).
327 .BR LIRC_SET_TRANSMITTER_MASK " (\fIint\fP)"
328 Enable the set of transmitters specified in
329 .IR val ,
330 which contains a bit mask where each enabled transmitter is a 1.
331 The first transmitter is encoded by the least significant bit, and so on.
332 When an invalid bit mask is given, for example a bit is set even
333 though the device does not have so many transmitters,
334 this operation returns the
335 number of available transmitters and does nothing otherwise.
337 .BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
338 Some devices are equipped with a special wide band receiver which is
339 intended to be used to learn the output of an existing remote.
340 This ioctl can be used to enable
341 .RI ( val
342 equals 1) or disable
343 .RI ( val
344 equals 0) this functionality.
345 This might be useful for devices that otherwise have narrow band
346 receivers that prevent them to be used with certain remotes.
347 Wide band receivers may also be more precise.
348 On the other hand, their disadvantage usually is reduced range of
349 reception.
351 Note: wide band receiver may be implicitly enabled if you enable
352 carrier reports.
353 In that case, it will be disabled as soon as you disable carrier reports.
354 Trying to disable a wide band receiver while carrier reports are active
355 will do nothing.
357 .SH FEATURES
359 .BR LIRC_GET_FEATURES
360 ioctl returns a bit mask describing features of the driver.
361 The following bits may be returned in the mask:
363 .BR LIRC_CAN_REC_MODE2
364 The driver is capable of receiving using
365 .BR LIRC_MODE_MODE2 .
367 .BR LIRC_CAN_REC_SCANCODE
368 The driver is capable of receiving using
369 .BR LIRC_MODE_SCANCODE .
371 .BR LIRC_CAN_SET_SEND_CARRIER
372 The driver supports changing the modulation frequency using
373 .BR LIRC_SET_SEND_CARRIER .
375 .BR LIRC_CAN_SET_SEND_DUTY_CYCLE
376 The driver supports changing the duty cycle using
377 .BR LIRC_SET_SEND_DUTY_CYCLE .
379 .BR LIRC_CAN_SET_TRANSMITTER_MASK
380 The driver supports changing the active transmitter(s) using
381 .BR LIRC_SET_TRANSMITTER_MASK .
383 .BR LIRC_CAN_SET_REC_CARRIER
384 The driver supports setting the receive carrier frequency using
385 .BR LIRC_SET_REC_CARRIER .
387 .B lirc
388 device since the drivers were merged in kernel release 2.6.36
389 must have
390 .BR LIRC_CAN_SET_REC_CARRIER_RANGE
391 set if
392 .BR LIRC_CAN_SET_REC_CARRIER
393 feature is set.
395 .BR LIRC_CAN_SET_REC_CARRIER_RANGE
396 The driver supports
397 .BR LIRC_SET_REC_CARRIER_RANGE .
398 The lower bound of the carrier must first be set using the
399 .BR LIRC_SET_REC_CARRIER_RANGE
400 ioctl, before using the
401 .BR LIRC_SET_REC_CARRIER
402 ioctl to set the upper bound.
404 .BR LIRC_CAN_GET_REC_RESOLUTION
405 The driver supports
406 .BR LIRC_GET_REC_RESOLUTION .
408 .BR LIRC_CAN_SET_REC_TIMEOUT
409 The driver supports
410 .BR LIRC_SET_REC_TIMEOUT .
412 .BR LIRC_CAN_MEASURE_CARRIER
413 The driver supports measuring of the modulation frequency using
414 .BR LIRC_SET_MEASURE_CARRIER_MODE .
416 .BR LIRC_CAN_USE_WIDEBAND_RECEIVER
417 The driver supports learning mode using
418 .BR LIRC_SET_WIDEBAND_RECEIVER .
420 .BR LIRC_CAN_SEND_PULSE
421 The driver supports sending using
422 .BR LIRC_MODE_PULSE
424 .BR LIRC_MODE_SCANCODE
426 .SH BUGS
427 Using these devices requires the kernel source header file
428 .IR lirc.h .
429 This file is not available before kernel release 4.6.
430 Users of older kernels could use the file bundled in
431 .UR http://www.lirc.org
432 .UE .
434 .SH SEE ALSO
435 \fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2)
437 https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html