source: udev-config/doc/55-lfs.txt@ a737f40

Purpose of rules file:

This is the core rules file for Udev on LFS.  If these rules were not included,
most devices would either only work for root, or would not work at all.


Description of rules:

By default, Udev creates device nodes with UID 0, GID 0, and permissions 0660,
and in one flat directory structure with all nodes in /dev.  This does not
always work well.

KERNEL=="ptmx"

Any uevent generated by the kernel with a name matching "ptmx" will match this
rule.  Note that the matching done by Udev is shell-style; these are not regex
matches.  For the ptmx device, we first change the permisions, by assigning to
the MODE value:

KERNEL=="ptmx", MODE="0666"

We also assign a different GID to /dev/ptmx (also all other TTY devices), by
assigning to the GROUP value:

KERNEL=="ptmx", MODE="0666", "GROUP="tty"


There are also devices that should not be in /dev, because historically they
have been created in subdirectories instead.  For instance, all Alsa devices
have traditionally been put into the /dev/snd subdirectory:

KERNEL=="controlC[0-9]*", <...>, NAME="snd/%k"

"%k" expands into "the original value of KERNEL" (note: not the pattern that was
matched against).  This type of rule puts any matching device into the snd/
subdirectory.

Sometimes we need to move devices based on more than just their name.  For
example, USB printer devices need to be moved to /dev/usb/lpX, but we can't
match only "lp[0-9]*", because that would also match parallel port printers.
So we match both KERNEL and SUBSYSTEMS in this case, to move USB printers only.


Some devices also commonly have symlinks pointing to them -- for example,
/dev/mouse is usually a symlink to /dev/input/mice.  We acheive this by
assigning to the SYMLINK value.  But note that SYMLINK can store multiple values
(because each device node could have multiple symlinks pointing to it), so we
need to add to the list of symlinks, not overwrite the whole list:

KERNEL=="mice", <...>, SYMLINK+="mouse"

If we needed to add multiple symlinks, they would be space-separated inside the
double quotes.

Of course, symlinks, permissions, and device names can all be combined in a
rule if needed.  But note that if you combine permissions and symlinks, or if
you combine GROUP and symlinks, the permissions of the symlink will not be
modified, only those of the target device.  (This is because the kernel does
not pay any attention to the permissions on symlinks, only the permissions on
their targets, and there's no reason to change something that won't be used.)


Finally, we have this rule:

SUBSYSTEM=="usb_device", PROGRAM="/bin/sh -c 'X=%k; X=$${X#usbdev}; B=$${X%%%%.*} D=$${X#*.}; echo bus/usb/$$B/$$D'", NAME="%c"

This rule matches any device under the SUBSYSTEM of usb_device.  (All devices
that were traditionally created under /proc/bus/usb/ use this subsystem.)  We
tell Udev to run the specified PROGRAM; Udev will save the output of this
program (it will be available under %c later).

The program itself is a shell that starts by setting the variable X to the
original kernel name (which is "usbdevB.D" for these devices, where B and D are
the bus and device numbers of the USB device).  Then, the rule re-sets X to the
value of X with the string "usbdev" removed from the start.  So now, X has the
value "B.D".  Then, the rule sets B to the value of X after a period, and all
characters following it, have been removed from the end; this sets B to just
the string "B" (just the bus number of the USB device).  Then, the rule sets D
to the value of X after a period, and all characters before it, have been
removed from the beginning; this sets D to just the string "D" (just the device
number).

Then, the rule echoes "bus/usb/$B/$D" (bus/usb/bus-number/device-number), so
Udev will capture that value.  The rule sets NAME="%c" to put the device node
at /dev/bus/usb/bus-number/device-number.  (This is the same layout that the
/proc/bus/usb/ devices used.)

Most of the doubled characters in this rule are doubled so that Udev does not
interpret them.  The rule looks all the more confusing because of this method
of escaping special characters.


A final word of caution: Any particular rule must be written on one line, and a
comma must separate each part of the rule.