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