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