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