| 1 |
'\" t |
| 2 |
.TH "HWDB" "7" "" "systemd 261~rc3" "hwdb" |
| 3 |
.\" ----------------------------------------------------------------- |
| 4 |
.\" * Define some portability stuff |
| 5 |
.\" ----------------------------------------------------------------- |
| 6 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 7 |
.\" http://bugs.debian.org/507673 |
| 8 |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| 9 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 10 |
.ie \n(.g .ds Aq \(aq |
| 11 |
.el .ds Aq ' |
| 12 |
.\" ----------------------------------------------------------------- |
| 13 |
.\" * set default formatting |
| 14 |
.\" ----------------------------------------------------------------- |
| 15 |
.\" disable hyphenation |
| 16 |
.nh |
| 17 |
.\" disable justification (adjust text to left margin only) |
| 18 |
.ad l |
| 19 |
.\" ----------------------------------------------------------------- |
| 20 |
.\" * MAIN CONTENT STARTS HERE * |
| 21 |
.\" ----------------------------------------------------------------- |
| 22 |
.SH "NAME" |
| 23 |
hwdb \- Hardware Database |
| 24 |
.SH "DESCRIPTION" |
| 25 |
.PP |
| 26 |
The hardware database is a key\-value store for associating modalias\-like keys to udev\-property\-like values\&. It is used primarily by udev to add the relevant properties to matching devices, but it can also be queried directly\&. |
| 27 |
.SH "HARDWARE DATABASE FILES" |
| 28 |
.PP |
| 29 |
The hwdb files are read from the files located in the system hwdb directory |
| 30 |
/usr/lib/udev/hwdb\&.d |
| 31 |
and the local administration directory |
| 32 |
/etc/udev/hwdb\&.d\&. All hwdb files are collectively sorted and processed in lexicographic order, regardless of the directories in which they live\&. However, files with identical filenames replace each other\&. Files in |
| 33 |
/etc/ |
| 34 |
have the highest priority and take precedence over files with the same name in |
| 35 |
/usr/lib/\&. This can be used to override a system\-supplied hwdb file with a local file if needed; a symlink in |
| 36 |
/etc/ |
| 37 |
with the same name as a hwdb file in |
| 38 |
/usr/lib/, pointing to |
| 39 |
/dev/null, disables that hwdb file entirely\&. hwdb files must have the extension |
| 40 |
\&.hwdb; other extensions are ignored\&. |
| 41 |
.PP |
| 42 |
Each hwdb file contains data records consisting of matches and associated key\-value pairs\&. Every record in the hwdb starts with one or more match strings, specifying a shell glob to compare the lookup string against\&. Multiple match lines are specified in consecutive lines\&. Every match line is compared individually, and they are combined by OR\&. Every match line must start at the first character of the line\&. |
| 43 |
.PP |
| 44 |
Match patterns consist of literal characters, and shell\-style wildcards: |
| 45 |
.sp |
| 46 |
.RS 4 |
| 47 |
.ie n \{\ |
| 48 |
\h'-04'\(bu\h'+03'\c |
| 49 |
.\} |
| 50 |
.el \{\ |
| 51 |
.sp -1 |
| 52 |
.IP \(bu 2.3 |
| 53 |
.\} |
| 54 |
Asterisk |
| 55 |
"*" |
| 56 |
matches any number of characters |
| 57 |
.RE |
| 58 |
.sp |
| 59 |
.RS 4 |
| 60 |
.ie n \{\ |
| 61 |
\h'-04'\(bu\h'+03'\c |
| 62 |
.\} |
| 63 |
.el \{\ |
| 64 |
.sp -1 |
| 65 |
.IP \(bu 2.3 |
| 66 |
.\} |
| 67 |
Question mark |
| 68 |
"?" |
| 69 |
matches a single character |
| 70 |
.RE |
| 71 |
.sp |
| 72 |
.RS 4 |
| 73 |
.ie n \{\ |
| 74 |
\h'-04'\(bu\h'+03'\c |
| 75 |
.\} |
| 76 |
.el \{\ |
| 77 |
.sp -1 |
| 78 |
.IP \(bu 2.3 |
| 79 |
.\} |
| 80 |
Character list |
| 81 |
"[\fIchars\fR]" |
| 82 |
matches one of the characters |
| 83 |
\fIchars\fR |
| 84 |
listed between |
| 85 |
"[" |
| 86 |
and |
| 87 |
"]"\&. A range may be specified as with a dash as |
| 88 |
"[\fIfirst\fR\-\fIlast\fR]"\&. The match may be inverted with a caret |
| 89 |
"[^\&...]"\&. |
| 90 |
.RE |
| 91 |
.PP |
| 92 |
The match lines are followed by one or more key\-value pair lines, which are recognized by a leading space character\&. The key name and value are separated by |
| 93 |
"="\&. An empty line signifies the end of a record\&. Lines beginning with |
| 94 |
"#" |
| 95 |
are ignored\&. |
| 96 |
.PP |
| 97 |
In case multiple records match a given lookup string, the key\-value pairs from all records are combined\&. If a key is specified multiple times, the value from the record with the highest priority is used (each key can have only a single value)\&. The priority is higher when the record is in a file that sorts later lexicographically, and in case of records in the same file, later records have higher priority\&. |
| 98 |
.PP |
| 99 |
The content of all hwdb files is read by |
| 100 |
\fBsystemd-hwdb\fR(8) |
| 101 |
and compiled to a binary database located at |
| 102 |
/etc/udev/hwdb\&.bin, or alternatively |
| 103 |
/usr/lib/udev/hwdb\&.bin |
| 104 |
if you want ship the compiled database in an immutable image\&. During runtime, only the binary database is used\&. |
| 105 |
.SH "EXAMPLES" |
| 106 |
.PP |
| 107 |
\fBExample\ \&1.\ \&General syntax of hwdb files\fR |
| 108 |
.sp |
| 109 |
.if n \{\ |
| 110 |
.RS 4 |
| 111 |
.\} |
| 112 |
.nf |
| 113 |
# /usr/lib/udev/hwdb\&.d/example\&.hwdb |
| 114 |
# Comments can be placed before any records\&. This is a good spot |
| 115 |
# to describe what that file is used for, what kind of properties |
| 116 |
# it defines, and the ordering convention\&. |
| 117 |
|
| 118 |
# A record with three matches and one property |
| 119 |
mouse:*:name:*Trackball*:* |
| 120 |
mouse:*:name:*trackball*:* |
| 121 |
mouse:*:name:*TrackBall*:* |
| 122 |
ID_INPUT_TRACKBALL=1 |
| 123 |
|
| 124 |
# The rule above could be also be written in a form that |
| 125 |
# matches Tb, tb, TB, tB: |
| 126 |
mouse:*:name:*[tT]rack[bB]all*:* |
| 127 |
ID_INPUT_TRACKBALL=1 |
| 128 |
|
| 129 |
# A record with a single match and five properties |
| 130 |
mouse:usb:v046dp4041:name:Logitech MX Master:* |
| 131 |
MOUSE_DPI=1000@166 |
| 132 |
MOUSE_WHEEL_CLICK_ANGLE=15 |
| 133 |
MOUSE_WHEEL_CLICK_ANGLE_HORIZONTAL=26 |
| 134 |
MOUSE_WHEEL_CLICK_COUNT=24 |
| 135 |
MOUSE_WHEEL_CLICK_COUNT_HORIZONTAL=14 |
| 136 |
.fi |
| 137 |
.if n \{\ |
| 138 |
.RE |
| 139 |
.\} |
| 140 |
.PP |
| 141 |
\fBExample\ \&2.\ \&Overriding of properties\fR |
| 142 |
.sp |
| 143 |
.if n \{\ |
| 144 |
.RS 4 |
| 145 |
.\} |
| 146 |
.nf |
| 147 |
# /usr/lib/udev/hwdb\&.d/60\-keyboard\&.hwdb |
| 148 |
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer*:pn*:* |
| 149 |
KEYBOARD_KEY_a1=help |
| 150 |
KEYBOARD_KEY_a2=setup |
| 151 |
KEYBOARD_KEY_a3=battery |
| 152 |
|
| 153 |
# Match vendor name "Acer" and any product name starting with "X123" |
| 154 |
evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer:pnX123*:* |
| 155 |
KEYBOARD_KEY_a2=wlan |
| 156 |
|
| 157 |
# /etc/udev/hwdb\&.d/70\-keyboard\&.hwdb |
| 158 |
# disable wlan key on all at keyboards |
| 159 |
evdev:atkbd:* |
| 160 |
KEYBOARD_KEY_a2=reserved |
| 161 |
PROPERTY_WITH_SPACES=some string |
| 162 |
.fi |
| 163 |
.if n \{\ |
| 164 |
.RE |
| 165 |
.\} |
| 166 |
.PP |
| 167 |
If the hwdb consists of those two files, a keyboard with the lookup string |
| 168 |
"evdev:atkbd:dmi:bvnAcer:bvr:bdXXXXX:bd08/05/2010:svnAcer:pnX123:" |
| 169 |
will match all three records, and end up with the following properties: |
| 170 |
.sp |
| 171 |
.if n \{\ |
| 172 |
.RS 4 |
| 173 |
.\} |
| 174 |
.nf |
| 175 |
KEYBOARD_KEY_a1=help |
| 176 |
KEYBOARD_KEY_a2=reserved |
| 177 |
KEYBOARD_KEY_a3=battery |
| 178 |
PROPERTY_WITH_SPACES=some string |
| 179 |
.fi |
| 180 |
.if n \{\ |
| 181 |
.RE |
| 182 |
.\} |
| 183 |
.SH "SEE ALSO" |
| 184 |
.PP |
| 185 |
\fBsystemd-hwdb\fR(8) |