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