man/hwdb.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright 2014 Tom Gundersen
   9   Copyright 2016 Zbigniew Jędrzejewski-Szmek
  10 -->
  11
  12 <refentry id="hwdb" conditional="ENABLE_HWDB">
  13   <refentryinfo>
  14     <title>hwdb</title>
  15     <productname>systemd</productname>
  16     <authorgroup>
  17       <author>
  18         <contrib>Developer</contrib>
  19         <firstname>Kay</firstname>
  20         <surname>Sievers</surname>
  21         <email>kay@vrfy.org</email>
  22       </author>
  23       <author>
  24         <contrib>Developer</contrib>
  25         <firstname>Tom</firstname>
  26         <surname>Gundersen</surname>
  27         <email>teg@jklm.no</email>
  28       </author>
  29     </authorgroup>
  30   </refentryinfo>
  31
  32   <refmeta>
  33     <refentrytitle>hwdb</refentrytitle>
  34     <manvolnum>7</manvolnum>
  35   </refmeta>
  36
  37   <refnamediv>
  38     <refname>hwdb</refname>
  39     <refpurpose>Hardware Database</refpurpose>
  40   </refnamediv>
  41
  42   <refsect1><title>Description</title>
  43     <para>The hardware database is a key-value store for associating modalias-like keys to
  44     udev-property-like values. It is used primarily by udev to add the relevant properties
  45     to matching devices, but it can also be queried directly.</para>
  46   </refsect1>
  47
  48   <refsect1><title>Hardware Database Files</title>
  49       <para>The hwdb files are read from the files located in the
  50       system hwdb directory <filename>/usr/lib/udev/hwdb.d</filename> and
  51       the local administration directory <filename>/etc/udev/hwdb.d</filename>.
  52       All hwdb files are collectively sorted and processed in lexical order,
  53       regardless of the directories in which they live. However, files with
  54       identical filenames replace each other. Files in <filename>/etc</filename>
  55       have the highest priority and take precedence over files with the same
  56       name in <filename>/usr/lib</filename>. This can be used to override a
  57       system-supplied hwdb file with a local file if needed;
  58       a symlink in <filename>/etc</filename> with the same name as a hwdb file in
  59       <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>,
  60       disables that hwdb file entirely. hwdb files must have the extension
  61       <filename>.hwdb</filename>; other extensions are ignored.</para>
  62
  63       <para>Each hwdb file contains data records consisting of matches and associated
  64       key-value pairs. Every record in the hwdb starts with one or more match strings,
  65       specifying a shell glob to compare the lookup string against. Multiple match lines
  66       are specified in consecutive lines. Every match line is compared individually, and
  67       they are combined by OR. Every match line must start at the first character of the
  68       line.</para>
  69
  70       <para>The match lines are followed by one or more key-value pair lines, which are
  71       recognized by a leading space character. The key name and value are separated by
  72       <literal>=</literal>. An empty line signifies the end of a record. Lines beginning
  73       with <literal>#</literal> are ignored.</para>
  74
  75       <para>In case multiple records match a given lookup string, the key-value pairs
  76       from all records are combined. If a key is specified multiple times, the value
  77       from the record with the highest priority is used (each key can have only a single
  78       value). The priority is higher when the record is in a file that sorts later
  79       lexicographically, and in case of records in the same file, later records have
  80       higher priority.</para>
  81
  82       <para>The content of all hwdb files is read by
  83       <citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  84       and compiled to a binary database located at <filename>/etc/udev/hwdb.bin</filename>,
  85       or alternatively <filename>/usr/lib/udev/hwdb.bin</filename> if you want ship the
  86       compiled database in an immutable image.  During runtime, only the binary database
  87       is used.</para>
  88   </refsect1>
  89
  90   <refsect1>
  91     <title>Examples</title>
  92
  93     <example>
  94       <title>General syntax of hwdb files</title>
  95
  96       <programlisting># /usr/lib/udev/hwdb.d/example.hwdb
  97 # Comments can be placed before any records. This is a good spot
  98 # to describe what that file is used for, what kind of properties
  99 # it defines, and the ordering convention.
 100
 101 # A record with three matches and one property
 102 mouse:*:name:*Trackball*:
 103 mouse:*:name:*trackball*:
 104 mouse:*:name:*TrackBall*:
 105  ID_INPUT_TRACKBALL=1
 106
 107 # A record with a single match and five properties
 108 mouse:usb:v046dp4041:name:Logitech MX Master:
 109  MOUSE_DPI=1000@166
 110  MOUSE_WHEEL_CLICK_ANGLE=15
 111  MOUSE_WHEEL_CLICK_ANGLE_HORIZONTAL=26
 112  MOUSE_WHEEL_CLICK_COUNT=24
 113  MOUSE_WHEEL_CLICK_COUNT_HORIZONTAL=14
 114 </programlisting>
 115     </example>
 116
 117     <example>
 118       <title>Overriding of properties</title>
 119
 120       <programlisting># /usr/lib/udev/hwdb.d/60-keyboard.hwdb
 121 evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer*:pn*
 122  KEYBOARD_KEY_a1=help
 123  KEYBOARD_KEY_a2=setup
 124  KEYBOARD_KEY_a3=battery
 125
 126 evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer*:pn123*
 127  KEYBOARD_KEY_a2=wlan
 128
 129 # /etc/udev/hwdb.d/70-keyboard.hwdb
 130 # disable wlan key on all at keyboards
 131 evdev:atkbd:*
 132  KEYBOARD_KEY_a2=reserved</programlisting>
 133
 134       <para>If the hwdb consists of those two files, a keyboard with the lookup string
 135       <literal>evdev:atkbd:dmi:bvnAcer:bdXXXXX:bd08/05/2010:svnAcer:pn123</literal>
 136       will match all three records, and end up with the following properties:</para>
 137
 138       <programlisting>KEYBOARD_KEY_a1=help
 139 KEYBOARD_KEY_a2=reserved
 140 KEYBOARD_KEY_a3=battery</programlisting>
 141     </example>
 142   </refsect1>
 143
 144   <refsect1>
 145     <title>See Also</title>
 146     <para>
 147       <citerefentry>
 148         <refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum>
 149       </citerefentry>
 150     </para>
 151   </refsect1>
 152 </refentry>