Provided by: lirc_0.10.1-6.3ubuntu1_amd64 bug

NAME

       lircd - Decode infrared signals and provide them on a socket.

SYNOPSIS

       lircd [options] [config file]

DESCRIPTION

       The  main task of lircd is to decode the infrared signals and provide an uniform interface
       for client applications. Clients can connect to lircd through a  Unix  domain  socket,  by
       default  /var/run/lirc/lircd.  Using this socket they will get the infrared codes received
       by lircd and they can send commands to lircd.

ARGUMENTS

       config file
           The  configuration  file,  by  default  /etc/lirc/lircd.conf.  A  relative   path   is
           interpreted  from  /etc/lirc.  The  default  configuration  file includes all files in
           /etc/lircd.conf.d.

           Each remote which should be decoded by lircd usually requires that a specific file  is
           used  e.  g.,  by  copying  it  to /etc/lirc/lirc.conf.d/.  The format is described in
           lircd.conf(5). Configuration files could be found using irdb-get(1) or  lirc-setup(1).
           It's also possible to generate a config file using irrecord(1)

OPTIONS

       Common options:

       -d, --device <device>
           Select  the  character  device  which lircd should read from. The default is currently
           /dev/lirc0 on most systems.

           Some drivers, including the default devinput driver, supports the  auto  device  which
           picks the first usable device found for the actual driver.

           When  using  the  devinput driver name=STRING or phys=STRING can be used to select the
           device; lircd will look in /dev/input to find a device with  a  matching  description.
           This is useful in case the device name isn't fixed. STRING may contain the '*' and '?'
           wildcards and '\' to mark them as literal.  Use mode2 --driver devinput --list-devices
           to list the actual devices.

       -H, --driver <driver>
           The  driver  to  use.   Using  --driver  help  lists all available drivers, see DRIVER
           LOADING below.

       -h, --help
           Displays short help message.

       Other options:

       -a, --allow-simulate
           Enable the SIMULATE command which can be issued using irsend(1)  or  the  client  API.
           This  will allow simulating arbitrary IR events from the command line. Use this option
           with caution because it will give all users with  access  to  the  lircd  socket  wide
           control  over  the system.  E.g., if you have configured your system to shut down by a
           button press on your remote control, everybody will be able to shut down  your  system
           from the command line.

       -c, --connect [host[:port]][,[host[:port]]]
           Connects  to  other  lircd servers that provide a network socket at the given host and
           port number (see --listen). The number of such connections  is  currently  limited  to
           100.   The connecting lircd instance will receive IR events from the lircd instance it
           connects to. To connect to multiple servers, add them as a comma separated list.

       -e, --effective-user <uid>
           If started as user root, lircd drops it  privileges  and  runs  as  user  <uid>  after
           opening files etc.

       -i, --immediate-init
           Lircd  normally  initializes the driver when the first client connects. If this option
           is selected, the driver is instead initialized immediately at start.

       -A, --driver-options key:value[|key:value...]
           Set one or more options for the driver. The argument is  a  list  of  key:value  pairs
           delimited  by  '|'.  The key can not contain spaces, but such are allowed in the value
           part. Certain characters including '#' and ';' are used  as  comment  markers  in  the
           config file and are not allowed anywhere.

       -Y, --dynamic-codes  [EXPERIMENTAL]
           Allows  use  of  codes  which  have been decoded for one remote but are not defined in
           lircd.conf.  New codes are dynamically created  with a default name. This  feature  is
           experimental and subject to all sorts of changes. It has not ben tested thoroughly.

       -l, --listen [[address:]port]]
           Let  lircd  listen  for  network  connections  on  the given address/port. The default
           address is 0.0.0.0, which means that connections on all  network  interfaces  will  be
           accepted.   The  address  must  be  given  in dotted numerical form.  Port defaults to
           8765.  The listening lircd instance will send all IR events to  the  connecting  lircd
           instances without any security checks.

           On  non-glibc platforms the address:port argument is mandatory, but can be given as an
           empty string e. g. --listen= which then defaults to 0.0.0.0:8765.

       -L, --logfile <logfile path>
           Select the lircd daemon log file. logfile is either  the  string  'syslog'  indicating
           that syslog(1) should be used or a log file path. The default is to use syslog.

       -D, --loglevel [level]
           Determine  the  amount  of  logging information. level can be a symbolic syslog level:
           'error','warning, 'info', 'notice' or  'debug'.  lircd also defines  three  additional
           levels  'trace',  'trace1'  and  'trace2'  which  gives  even  more messages ('trace2'
           bringing the most).  However, in the log these messages are marked as 'debug'.

           On non-glibc platforms the level argument is mandatory, but can be given as  an  empty
           string e. g. --loglevel= which then defaults to debug.

           The level can also be an integer in the range 3 (almost no messages) to 10.

       -O, --options-file <path>
           File  containing  default  values for all options. A relative path is interpreted from
           current directory. See [FILES] below.

       -o, --output <output socket>
           Select Unix domain socket, which lircd will write remote key codes  to.   The  default
           currently is /var/run/lirc/lircd.

       -p, --permission <perm>
           Gives  the  file  permission  of  the  output  socket if it has to be created in octal
           representation. See chmod(1).  If no --permission option is given when the  socket  is
           initially created the default is to give all users read and write permissions (0666 in
           octal representation). If the socket already exists this option has no effect.

       -p, --pidfile <path>
           Select the lircd daemon pid file, defaults to /var/run/lirc/lircd.pid.

       -U --plugindir <path>
           Sets the directory from which lircd loads  it's  userspace  drivers.  These  are  *.so
           files,  by  default  found  as  described  under  DRIVER  LOADING.  The  argument is a
           :-separated search path.

       -r, --release [suffix]
           This option is deprecated and will be removed  in  an  upcoming  release.  See  lircd-
           uinput(8) for a replacement.

           Enables  automatic  generation  of  release  events for each button press.  lircd will
           append the given suffix to the button name for each release event.  If  no  suffix  is
           given the default suffix is '_EVUP'.

           Note  the  suffix  _UP,  which was used by lircd prior to 0.10.0, is used by the linux
           kernel for other purposes since 4.7.

       -R, --repeat-max <limit>
           Sets an upper limit to the number of  repeats  when  sending  a  signal.  The  current
           default  is 600. A SEND_START request will repeat the signal this many times. Also, if
           the number of repeats in a SEND_ONCE request exceeds this number, it will be  replaced
           by this number.

SOCKET BROADCAST MESSAGES FORMAT

       When  decoding  a  button  press  or receiving a SIGHUP signal lircd.conf lircd broadcasts
       messages to all connected clients.

       For each decoded button press a package is made available on the socket. This is printable
       data formatted as:
               <code> <repeat count> <button name> <remote control name>

       e.g.,
               0000000000f40bf0 00 KEY_UP ANIMAX

       The fields are:

       code
           A  16 hexadecimal digits number encoding of the IR signal.  It's usage in applications
           is deprecated and it should be ignored.

       repeat count
           shows how long the user has been holding down a button. The counter will  start  at  0
           and increment each time a new IR signal has been received.

       button name
           is the name of a key defined in the lircd.conf file.

       remote control name
           is the mandatory name attribute in the lircd.conf config file.

       These  packets  are  broadcasted  to  all  clients.  The  only  other situation when lircd
       broadcasts to all clients is when it receives the SIGHUP signal and successfully  re-reads
       its  config  file.  Then  it  will send a SIGHUP packet to its clients indicating that its
       configuration might have changed.  The sighup packet is three lines

               BEGIN
               SIGHUP
               END

SOCKET COMMAND INTERFACE

       Applications can also send commands to lircd over the socket interface.  The  most  common
       task  is  sending  data,  but  there  are  also  other commands.  Each command is a single
       printable line, terminated with a newline. For each command, lircd replies  with  a  reply
       package.

       Supported commands:

       SEND_ONCE <remote control> <button name> [repeats]
           Tell  lircd  to send the IR signal associated with the given remote control and button
           name, and then repeat it repeats times.  repeats is a decimal  number  between  0  and
           repeat_max.  The latter can be given as a --repeat-max command line argument to lircd,
           and defaults to 600.  If repeats is not specified or is less than the  minimum  number
           of repeats for the selected remote control, the minimum value will be used.

       SEND_START <remote control name> <button name>
           Tell  lircd to start repeating the given button until it receives a SEND_STOP command.
           However, the number of repeats is limited to repeat_max. lircd won't  accept  any  new
           send commands while it is repeating.

       SEND_STOP <remote control name> <button name>
           Tell lircd to abort a SEND_START command.

       LIST [remote control]
           Without  arguments  lircd replies with a list of all defined remote controls.  Given a
           remote control argument, lircd replies with a list of all keys defined  in  the  given
           remote.

       SET_INPUTLOG [path]
           Given  a  path,  lircd  will start logging all received data on that file.  The log is
           printable lines as defined in mode2(1) describing pulse/space  durations.   Without  a
           path, current logfile is closed and the logging is stopped.

       DRV_OPTION key value
           Make lircd invoke the drvctl_func(DRVCTL_SET_OPTION, option) with option being made up
           by the parsed key  and  value.   The  return  package  reflects  the  outcome  of  the
           drvctl_func call.

       SIMULATE key data
           Given  key  data, instructs lircd to send this to all clients i.  e., to simulate that
           this key has been decoded.  The key data must  be  formatted  exactly  as  the  packet
           described  in  [SOCKET  BROADCAST MESSAGES FORMAT], notably is the number of digits in
           code and repeat count hardcoded.  This  command  is  only  accepted  if  the  --allow-
           simulate command line option is active.

       SET_TRANSMITTERS transmitter mask
           Make   lircd   invoke  the  drvctl_func(LIRC_SET_TRANSMITTER_MASK,  &channels),  where
           channels is the decoded value of transmitter mask. See lirc(4) for more information.

       VERSION
           Tell lircd to send a version packet response.

       The protocol guarantees that broadcasted messages won't interfere with reply packets.  But
       broadcasts  may  appear  at  any  point  between  packets.   The only exception are SIGHUP
       packages. These may appear just after you have sent a command to lircd,  so  you  have  to
       make sure you don't confuse them with replies.

       The format of the reply packet is

         BEGIN
         <command>
         [SUCCESS|ERROR]
         [DATA
         n
         n lines of data]
         END

       If  the  command  was  successful,  data  is  only  sent for the commands that return some
       information. Note that a packet containing 0 lines of data can be a valid reply.

RUNNING AS REGULAR USER

       Traditionally lircd  has  been  running  as  root  since  accessing  kernel  devices  like
       /dev/lirc0  by  default requires root privileges.  However, running a long-running service
       like this is a major security issue.

       The lirc distribution contains example udev rules which makes  /dev/lirc[0-9]  ,  USB  and
       serial  devices  accessible  by  the  lirc user.  Using these rules, it is possible to run
       lircd as a regular user and group such as lirc.

FILES

       /etc/lirc/lircd.conf
           Main config file, see lircd.conf(5).

       /etc/lirc/lirc_options.conf
           The options file. lircd handles the values under the [lircd] section in this file. The
           location  can  be changed using the -O/--options-file command-line option or using the
           environment variable LIRC_OPTIONS_PATH.  The values here are used as defaults for  any
           option not present on command line.

ENVIRONMENT

       LIRC_OPTIONS_PATH
           Options file path, see FILES.

       LIRC_PLUGINDIR
           Plugin load path, se DRIVER LOADING.

       LIRC_DEBUG_OPTIONS
           If set, enables debugging in early stages when the --debug option is yet not parsed.

DRIVER LOADING

       Drivers  are  loaded  dynamically.  This is done from a traditional *ux ´:´-separated path
       where each component in the path is searched (leading part first, trailing last).

       The path used for this is determined by (falling priority):

       - The --plugindir option.

       - The 'plugindir' entry in  the [lircd] section of the lirc_options.conf file.

       - The environment variable LIRC_PLUGINDIR.

       - A hardcoded default (/usr/lib/x86_64-linux-gnu/lirc/plugins).

SIGNALS

       HUP On receiving  SIGHUP  lircd  re-reads  the  lircd.conf  configuration  file  (but  not
           lirc_options.conf) and adjusts itself if the file has changed.

       USR1
           On receiving SIGUSR1 lircd makes a clean exit.

DAEMONS

       lircd   is  a  daemon.   It  should  be  started in some system-dependent init script.  By
       default, lirc ships with systemd files enabling user to control the lircd service.

SEE ALSO

       irdb-get(1)
       lirc-setup(1)
       lircd.conf(5)
       irrecord(1)
       lirc(4)
       lircd-uinput(8)