]>
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 | |
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 | ||
3715a071 | 27 | <refentry id="hwdb" conditional="ENABLE_HWDB"> |
65eb4378 TG |
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 | |
a8eaaee7 | 59 | udev-property-like values. It is used primarily by udev to add the relevant properties |
65eb4378 TG |
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 | |
12b42c76 TG |
65 | system hwdb directory <filename>/usr/lib/udev/hwdb.d</filename> and |
66 | the local administration directory <filename>/etc/udev/hwdb.d</filename>. | |
65eb4378 TG |
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> | |
12b42c76 TG |
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; | |
65eb4378 | 73 | a symlink in <filename>/etc</filename> with the same name as a hwdb file in |
12b42c76 | 74 | <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, |
dc17ee3d | 75 | disables that hwdb file entirely. hwdb files must have the extension |
65eb4378 TG |
76 | <filename>.hwdb</filename>; other extensions are ignored.</para> |
77 | ||
dc17ee3d ZJS |
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> | |
65eb4378 | 84 | |
dc17ee3d ZJS |
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> | |
65eb4378 TG |
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>, | |
dc17ee3d ZJS |
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> | |
65eb4378 TG |
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> |