← Back to branch summary

~juanje/udev/udev-acls-android

« back to all changes in this revision

Viewing changes to udev/udev.7

  • Committer: Bazaar Package Importer
  • Author(s): Scott James Remnant
  • Date: 2009-12-02 01:40:55 UTC
  • Revision ID: james.westby@ubuntu.com-20091202014055-g5f7k5z3db7njmlj
Tags: 148~-1
* Update to GIT HEAD:
  - Ignore_device option removed.
  - BUS, SYSFS and ID are now deprecated and result in a warning.
  - IDE device support removed from default rules.
  - New input_id helper, previous uses of the ID_CLASS property on
    input devices should now use the new ID_INPUT_* properties.  This
    is a big part of the Halsectomy of X.org

Show diffs side-by-side

added added

removed removed

Lines of Context:
udev/udev.7
1
 
'\" t
2
 
.\"     Title: udev
3
 
.\"    Author: [see the "AUTHOR" section]
4
 
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
5
 
.\"      Date: 11/10/2009
6
 
.\"    Manual: udev
7
 
.\"    Source: udev
8
 
.\"  Language: English
9
 
.\"
10
 
.TH "UDEV" "7" "11/10/2009" "udev" "udev"
11
 
.\" -----------------------------------------------------------------
12
 
.\" * set default formatting
13
 
.\" -----------------------------------------------------------------
14
 
.\" disable hyphenation
15
 
.nh
16
 
.\" disable justification (adjust text to left margin only)
17
 
.ad l
18
 
.\" -----------------------------------------------------------------
19
 
.\" * MAIN CONTENT STARTS HERE *
20
 
.\" -----------------------------------------------------------------
21
 
.SH "NAME"
22
 
udev \- dynamic device management
23
 
.SH "DESCRIPTION"
24
 
.PP
25
 
udev provides a dynamic device directory containing only the files for actually present devices\&. It creates or removes device node files in the
26
 
/dev
27
 
directory, or it renames network interfaces\&.
28
 
.PP
29
 
Usually udev runs as
30
 
\fBudevd\fR(8)
31
 
and receives uevents directly from the kernel if a device is added or removed from the system\&.
32
 
.PP
33
 
If udev receives a device event, it matches its configured rules against the available device attributes provided in sysfs to identify the device\&. Rules that match may provide additional device information or specify a device node name and multiple symlink names and instruct udev to run additional programs as part of the device event handling\&.
34
 
.SH "CONFIGURATION"
35
 
.PP
36
 
udev configuration files are placed in
37
 
/etc/udev/
38
 
and
39
 
/lib/udev/\&. All empty lines, or lines beginning with \'#\' will be ignored\&.
40
 
.SS "Configuration file"
41
 
.PP
42
 
udev expects its main configuration file at
43
 
/etc/udev/udev\&.conf\&. It consists of a set of variables allowing the user to override default udev values\&. The following variables can be set:
44
 
.PP
45
 
\fBudev_root\fR
46
 
.RS 4
47
 
Specifies where to place the device nodes in the filesystem\&. The default value is
48
 
/dev\&.
49
 
.RE
50
 
.PP
51
 
\fBudev_log\fR
52
 
.RS 4
53
 
The logging priority\&. Valid values are the numerical syslog priorities or their textual representations:
54
 
\fBerr\fR,
55
 
\fBinfo\fR
56
 
and
57
 
\fBdebug\fR\&.
58
 
.RE
59
 
.SS "Rules files"
60
 
.PP
61
 
The udev rules are read from the files located in the default rules directory
62
 
/lib/udev/rules\&.d/, the custom rules directory
63
 
/etc/udev/rules\&.d/
64
 
and the temporary rules directory
65
 
/dev/\&.udev/rules\&.d/\&. All rule files are sorted and processed in lexical order, regardless in which of these directories they live\&.
66
 
.PP
67
 
Rule files are required to have a unique name, duplicate file names are ignored\&. Files in
68
 
/etc/udev/rules\&.d/
69
 
have precedence over files with the same name in
70
 
/lib/udev/rules\&.d/\&. This can be used to ignore a default rules file if needed\&.
71
 
.PP
72
 
Every line in the rules file contains at least one key value pair\&. There are two kind of keys, match and assignment keys\&. If all match keys are matching against its value, the rule gets applied and the assign keys get the specified value assigned\&.
73
 
.PP
74
 
A matching rule may specify the name of the device node, add a symlink pointing to the node, or run a specified program as part of the event handling\&. If no matching rule is found, the default device node name is used\&.
75
 
.PP
76
 
A rule consists of a list of one or more key value pairs separated by a comma\&. Each key has a distinct operation, depending on the used operator\&. Valid operators are:
77
 
.PP
78
 
\fB==\fR
79
 
.RS 4
80
 
Compare for equality\&.
81
 
.RE
82
 
.PP
83
 
\fB!=\fR
84
 
.RS 4
85
 
Compare for inequality\&.
86
 
.RE
87
 
.PP
88
 
\fB=\fR
89
 
.RS 4
90
 
Assign a value to a key\&. Keys that represent a list, are reset and only this single value is assigned\&.
91
 
.RE
92
 
.PP
93
 
\fB+=\fR
94
 
.RS 4
95
 
Add the value to a key that holds a list of entries\&.
96
 
.RE
97
 
.PP
98
 
\fB:=\fR
99
 
.RS 4
100
 
Assign a value to a key finally; disallow any later changes, which may be used to prevent changes by any later rules\&.
101
 
.RE
102
 
.PP
103
 
The following key names can be used to match against device properties\&. Some of the keys also match against properties of the parent devices in sysfs, not only the device that has generated the event\&. If multiple keys that match a parent device are specified in a single rule, all these keys must match at one and the same parent device\&.
104
 
.PP
105
 
\fBACTION\fR
106
 
.RS 4
107
 
Match the name of the event action\&.
108
 
.RE
109
 
.PP
110
 
\fBDEVPATH\fR
111
 
.RS 4
112
 
Match the devpath of the event device\&.
113
 
.RE
114
 
.PP
115
 
\fBKERNEL\fR
116
 
.RS 4
117
 
Match the name of the event device\&.
118
 
.RE
119
 
.PP
120
 
\fBNAME\fR
121
 
.RS 4
122
 
Match the name of the node or network interface\&. It can be used once the NAME key has been set in one of the preceding rules\&.
123
 
.RE
124
 
.PP
125
 
\fBSYMLINK\fR
126
 
.RS 4
127
 
Match the name of a symlink targeting the node\&. It can be used once a SYMLINK key has been set in one of the preceding rules\&. There may be multiple symlinks; only one needs to match\&.
128
 
.RE
129
 
.PP
130
 
\fBSUBSYSTEM\fR
131
 
.RS 4
132
 
Match the subsystem of the event device\&.
133
 
.RE
134
 
.PP
135
 
\fBDRIVER\fR
136
 
.RS 4
137
 
Match the driver name of the event device\&. Only set for devices which are bound to a driver at the time the event is generated\&.
138
 
.RE
139
 
.PP
140
 
\fBATTR{\fR\fB\fIfilename\fR\fR\fB}\fR
141
 
.RS 4
142
 
Match sysfs attribute values of the event device\&. Trailing whitespace in the attribute values is ignored, if the specified match value does not contain trailing whitespace itself\&.
143
 
.RE
144
 
.PP
145
 
\fBKERNELS\fR
146
 
.RS 4
147
 
Search the devpath upwards for a matching device name\&.
148
 
.RE
149
 
.PP
150
 
\fBSUBSYSTEMS\fR
151
 
.RS 4
152
 
Search the devpath upwards for a matching device subsystem name\&.
153
 
.RE
154
 
.PP
155
 
\fBDRIVERS\fR
156
 
.RS 4
157
 
Search the devpath upwards for a matching device driver name\&.
158
 
.RE
159
 
.PP
160
 
\fBATTRS{\fR\fB\fIfilename\fR\fR\fB}\fR
161
 
.RS 4
162
 
Search the devpath upwards for a device with matching sysfs attribute values\&. If multiple
163
 
\fBATTRS\fR
164
 
matches are specified, all of them must match on the same device\&. Trailing whitespace in the attribute values is ignored, if the specified match value does not contain trailing whitespace itself\&.
165
 
.RE
166
 
.PP
167
 
\fBENV{\fR\fB\fIkey\fR\fR\fB}\fR
168
 
.RS 4
169
 
Match against a device property value\&.
170
 
.RE
171
 
.PP
172
 
\fBTEST{\fR\fB\fIoctal mode mask\fR\fR\fB}\fR
173
 
.RS 4
174
 
Test the existence of a file\&. An octal mode mask can be specified if needed\&.
175
 
.RE
176
 
.PP
177
 
\fBPROGRAM\fR
178
 
.RS 4
179
 
Execute a program\&. The key is true, if the program returns successfully\&. The device properties are made available to the executed program in the environment\&. The program\'s output printed to stdout, is available in the RESULT key\&.
180
 
.RE
181
 
.PP
182
 
\fBRESULT\fR
183
 
.RS 4
184
 
Match the returned string of the last PROGRAM call\&. This key can be used in the same or in any later rule after a PROGRAM call\&.
185
 
.RE
186
 
.PP
187
 
Most of the fields support a shell style pattern matching\&. The following pattern characters are supported:
188
 
.PP
189
 
\fB*\fR
190
 
.RS 4
191
 
Matches zero, or any number of characters\&.
192
 
.RE
193
 
.PP
194
 
\fB?\fR
195
 
.RS 4
196
 
Matches any single character\&.
197
 
.RE
198
 
.PP
199
 
\fB[]\fR
200
 
.RS 4
201
 
Matches any single character specified within the brackets\&. For example, the pattern string \'tty[SR]\' would match either \'ttyS\' or \'ttyR\'\&. Ranges are also supported within this match with the \'\-\' character\&. For example, to match on the range of all digits, the pattern [0\-9] would be used\&. If the first character following the \'[\' is a \'!\', any characters not enclosed are matched\&.
202
 
.RE
203
 
.PP
204
 
The following keys can get values assigned:
205
 
.PP
206
 
\fBNAME\fR
207
 
.RS 4
208
 
The name of the node to be created, or the name the network interface should be renamed to\&.
209
 
.RE
210
 
.PP
211
 
\fBSYMLINK\fR
212
 
.RS 4
213
 
The name of a symlink targeting the node\&. Every matching rule will add this value to the list of symlinks to be created along with the device node\&. Multiple symlinks may be specified by separating the names by the space character\&.
214
 
.RE
215
 
.PP
216
 
\fBOWNER, GROUP, MODE\fR
217
 
.RS 4
218
 
The permissions for the device node\&. Every specified value overwrites the compiled\-in default value\&.
219
 
.RE
220
 
.PP
221
 
\fBATTR{\fR\fB\fIkey\fR\fR\fB}\fR
222
 
.RS 4
223
 
The value that should be written to a sysfs attribute of the event device\&.
224
 
.RE
225
 
.PP
226
 
\fBENV{\fR\fB\fIkey\fR\fR\fB}\fR
227
 
.RS 4
228
 
Set a device property value\&. Property names with a leading \'\&.\' are not stored in the database or exported to external tool or events\&.
229
 
.RE
230
 
.PP
231
 
\fBRUN\fR
232
 
.RS 4
233
 
Add a program to the list of programs to be executed for a specific device\&. This can only be used for very short running tasks\&. Running an event process for a long period of time may block all further events for this or a dependent device\&. Long running tasks need to be immediately detached from the event process itself\&. If the option
234
 
\fBRUN{\fR\fB\fIfail_event_on_error\fR\fR\fB}\fR
235
 
is specified, and the executed program returns non\-zero, the event will be marked as failed for a possible later handling\&.
236
 
.sp
237
 
If the specified string starts with
238
 
\fBsocket:\fR\fB\fIpath\fR\fR, all current event values will be passed to the specified socket, as a message in the same format the kernel sends an uevent\&. If the first character of the specified path is an @ character, an abstract namespace socket is used, instead of an existing socket file\&.
239
 
.RE
240
 
.PP
241
 
\fBLABEL\fR
242
 
.RS 4
243
 
Named label where a GOTO can jump to\&.
244
 
.RE
245
 
.PP
246
 
\fBGOTO\fR
247
 
.RS 4
248
 
Jumps to the next LABEL with a matching name
249
 
.RE
250
 
.PP
251
 
\fBIMPORT{\fR\fB\fItype\fR\fR\fB}\fR
252
 
.RS 4
253
 
Import a set of variables as device properties, depending on
254
 
\fItype\fR:
255
 
.PP
256
 
\fBprogram\fR
257
 
.RS 4
258
 
Execute an external program specified as the assigned value and import its output, which must be in environment key format\&.
259
 
.RE
260
 
.PP
261
 
\fBfile\fR
262
 
.RS 4
263
 
Import a text file specified as the assigned value, which must be in environment key format\&.
264
 
.RE
265
 
.PP
266
 
\fBparent\fR
267
 
.RS 4
268
 
Import the stored keys from the parent device by reading the database entry of the parent device\&. The value assigned to
269
 
\fBIMPORT{parent}\fR
270
 
is used as a filter of key names to import (with the same shell\-style pattern matching used for comparisons)\&.
271
 
.RE
272
 
.sp
273
 
If no option is given, udev will choose between
274
 
\fBprogram\fR
275
 
and
276
 
\fBfile\fR
277
 
based on the executable bit of the file permissions\&.
278
 
.RE
279
 
.PP
280
 
\fBWAIT_FOR\fR
281
 
.RS 4
282
 
Wait for a file to become available\&.
283
 
.RE
284
 
.PP
285
 
\fBOPTIONS\fR
286
 
.RS 4
287
 
Rule and device options:
288
 
.PP
289
 
\fBignore_device\fR
290
 
.RS 4
291
 
Ignore this event completely\&.
292
 
.RE
293
 
.PP
294
 
\fBignore_remove\fR
295
 
.RS 4
296
 
Do not remove the device node when the device goes away\&. This may be useful as a workaround for broken device drivers\&.
297
 
.RE
298
 
.PP
299
 
\fBlink_priority=\fR\fB\fIvalue\fR\fR
300
 
.RS 4
301
 
Specify the priority of the created symlinks\&. Devices with higher priorities overwrite existing symlinks of other devices\&. The default is 0\&.
302
 
.RE
303
 
.PP
304
 
\fBall_partitions\fR
305
 
.RS 4
306
 
Create the device nodes for all available partitions of a block device\&. This may be useful for removable media devices where media changes are not detected\&.
307
 
.RE
308
 
.PP
309
 
\fBevent_timeout=\fR
310
 
.RS 4
311
 
Number of seconds an event will wait for operations to finish, before it will terminate itself\&.
312
 
.RE
313
 
.PP
314
 
\fBstring_escape=\fR\fB\fInone|replace\fR\fR
315
 
.RS 4
316
 
Usually control and other possibly unsafe characters are replaced in strings used for device naming\&. The mode of replacement can be specified with this option\&.
317
 
.RE
318
 
.PP
319
 
\fBwatch\fR
320
 
.RS 4
321
 
Watch the device node with inotify, when closed after being opened for writing, a change uevent will be synthesised\&.
322
 
.RE
323
 
.RE
324
 
.PP
325
 
The
326
 
\fBNAME\fR,
327
 
\fBSYMLINK\fR,
328
 
\fBPROGRAM\fR,
329
 
\fBOWNER\fR,
330
 
\fBGROUP\fR,
331
 
\fBMODE\fR
332
 
and
333
 
\fBRUN\fR
334
 
fields support simple printf\-like string substitutions\&. The
335
 
\fBRUN\fR
336
 
format chars gets applied after all rules have been processed, right before the program is executed\&. It allows the use of device properties set by earlier matching rules\&. For all other fields, substitutions are applied while the individual rule is being processed\&. The available substitutions are:
337
 
.PP
338
 
\fB$kernel\fR, \fB%k\fR
339
 
.RS 4
340
 
The kernel name for this device\&.
341
 
.RE
342
 
.PP
343
 
\fB$number\fR, \fB%n\fR
344
 
.RS 4
345
 
The kernel number for this device\&. For example, \'sda3\' has kernel number of \'3\'
346
 
.RE
347
 
.PP
348
 
\fB$devpath\fR, \fB%p\fR
349
 
.RS 4
350
 
The devpath of the device\&.
351
 
.RE
352
 
.PP
353
 
\fB$id\fR, \fB%b\fR
354
 
.RS 4
355
 
The name of the device matched while searching the devpath upwards for
356
 
\fBSUBSYSTEMS\fR,
357
 
\fBKERNELS\fR,
358
 
\fBDRIVERS\fR
359
 
and
360
 
\fBATTRS\fR\&.
361
 
.RE
362
 
.PP
363
 
\fB$driver\fR
364
 
.RS 4
365
 
The driver name of the device matched while searching the devpath upwards for
366
 
\fBSUBSYSTEMS\fR,
367
 
\fBKERNELS\fR,
368
 
\fBDRIVERS\fR
369
 
and
370
 
\fBATTRS\fR\&.
371
 
.RE
372
 
.PP
373
 
\fB$attr{\fR\fB\fIfile\fR\fR\fB}\fR, \fB%s{\fR\fB\fIfile\fR\fR\fB}\fR
374
 
.RS 4
375
 
The value of a sysfs attribute found at the device, where all keys of the rule have matched\&. If the matching device does not have such an attribute, follow the chain of parent devices and use the value of the first attribute that matches\&. If the attribute is a symlink, the last element of the symlink target is returned as the value\&.
376
 
.RE
377
 
.PP
378
 
\fB$env{\fR\fB\fIkey\fR\fR\fB}\fR, \fB%E{\fR\fB\fIkey\fR\fR\fB}\fR
379
 
.RS 4
380
 
A device property value\&.
381
 
.RE
382
 
.PP
383
 
\fB$major\fR, \fB%M\fR
384
 
.RS 4
385
 
The kernel major number for the device\&.
386
 
.RE
387
 
.PP
388
 
\fB$minor\fR, \fB%m\fR
389
 
.RS 4
390
 
The kernel minor number for the device\&.
391
 
.RE
392
 
.PP
393
 
\fB$result\fR, \fB%c\fR
394
 
.RS 4
395
 
The string returned by the external program requested with PROGRAM\&. A single part of the string, separated by a space character may be selected by specifying the part number as an attribute:
396
 
\fB%c{N}\fR\&. If the number is followed by the \'+\' char this part plus all remaining parts of the result string are substituted:
397
 
\fB%c{N+}\fR
398
 
.RE
399
 
.PP
400
 
\fB$parent\fR, \fB%P\fR
401
 
.RS 4
402
 
The node name of the parent device\&.
403
 
.RE
404
 
.PP
405
 
\fB$name\fR
406
 
.RS 4
407
 
The current name of the device node\&. If not changed by a rule, it is the name of the kernel device\&.
408
 
.RE
409
 
.PP
410
 
\fB$links\fR
411
 
.RS 4
412
 
The current list of symlinks, separated by a space character\&. The value is only set if an earlier rule assigned a value, or during a remove events\&.
413
 
.RE
414
 
.PP
415
 
\fB$root\fR, \fB%r\fR
416
 
.RS 4
417
 
The udev_root value\&.
418
 
.RE
419
 
.PP
420
 
\fB$sys\fR, \fB%S\fR
421
 
.RS 4
422
 
The sysfs mount point\&.
423
 
.RE
424
 
.PP
425
 
\fB$tempnode\fR, \fB%N\fR
426
 
.RS 4
427
 
The name of a created temporary device node to provide access to the device from a external program before the real node is created\&.
428
 
.RE
429
 
.PP
430
 
\fB%%\fR
431
 
.RS 4
432
 
The \'%\' character itself\&.
433
 
.RE
434
 
.PP
435
 
\fB$$\fR
436
 
.RS 4
437
 
The \'$\' character itself\&.
438
 
.RE
439
 
.SH "AUTHOR"
440
 
.PP
441
 
Written by Greg Kroah\-Hartman
442
 
greg@kroah\&.com
443
 
and Kay Sievers
444
 
kay\&.sievers@vrfy\&.org\&. With much help from Dan Stekloff and many others\&.
445
 
.SH "SEE ALSO"
446
 
.PP
447
 
\fBudevd\fR(8),
448
 
\fBudevadm\fR(8)