Update udev-lfs-199 for man pages and html docs

git-svn-id: http://svn.linuxfromscratch.org/LFS/trunk/BOOK@10227 4aa44e1e-78dd-0310-a6d2-fbcd4c07a689

1 files changed, 476 insertions, 0 deletions

diff --git a/udev-lfs/udev.7 b/udev-lfs/udev.7
new file mode 100644
index 000000000..1cdd926e3
--- /dev/null
+++ b/udev-lfs/udev.7
@@ -0,0 +1,476 @@
+'\" t
+.TH "UDEV" "7" "" "systemd 199" "udev"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+udev \- Linux dynamic device management
+.SH "DESCRIPTION"
+.PP
+udev supplies the system software with device events, manages permissions of device nodes and may create additional symlinks in the
+/dev
+directory, or renames network interfaces\&. The kernel usually just assigns unpredictable device names based on the order of discovery\&. Meaningful symlinks or network device names provide a way to reliably identify devices based on their properties or current configuration\&.
+.PP
+The udev daemon,
+\fBudevd\fR(8), receives device uevents directly from the kernel whenever a device is added or removed from the system, or it changes its state\&. When udev receives a device event, it matches its configured set of rules against various device attributes to identify the device\&. Rules that match may provide additional device information to be stored in the udev database or to be used to create meaningful symlink names\&.
+.PP
+All device information udev processes is stored in the udev database and sent out to possible event subscribers\&. Access to all stored data and the event sources is provided by the library libudev\&.
+.SH "RULES FILES"
+.PP
+The udev rules are read from the files located in the system rules directory
+/usr/lib/udev/rules\&.d, the volatile runtime directory
+/run/udev/rules\&.d
+and the local administration directory
+/etc/udev/rules\&.d\&. All rules files are collectively sorted and processed in lexical order, regardless of the directories in which they live\&. However, files with identical file names replace each other\&. Files in
+/etc
+have the highest priority, files in
+/run
+take precedence over files with the same name in
+/lib\&. This can be used to override a system\-supplied rules file with a local file if needed; a symlink in
+/etc
+with the same name as a rules file in
+/lib, pointing to
+/dev/null, disables the rules file entirely\&.
+.PP
+Rule files must have the extension
+\&.rules; other extensions are ignored\&.
+.PP
+Every line in the rules file contains at least one key\-value pair\&. Except for empty lines or lines beginning with \*(Aq#\*(Aq, which are ignored\&. There are two kinds of keys: match and assignment\&. If all match keys match against their values, the rule gets applied and the assignment keys get the specified values assigned\&.
+.PP
+A matching rule may rename a network interface, add symlinks pointing to the device node, or run a specified program as part of the event handling\&.
+.PP
+A rule consists of a comma\-separated list of one or more key\-value pairs\&. Each key has a distinct operation, depending on the used operator\&. Valid operators are:
+.PP
+==
+.RS 4
+Compare for equality\&.
+.RE
+.PP
+!=
+.RS 4
+Compare for inequality\&.
+.RE
+.PP
+=
+.RS 4
+Assign a value to a key\&. Keys that represent a list are reset and only this single value is assigned\&.
+.RE
+.PP
++=
+.RS 4
+Add the value to a key that holds a list of entries\&.
+.RE
+.PP
+:=
+.RS 4
+Assign a value to a key finally; disallow any later changes\&.
+.RE
+.PP
+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\&.
+.PP
+\fBACTION\fR
+.RS 4
+Match the name of the event action\&.
+.RE
+.PP
+\fBDEVPATH\fR
+.RS 4
+Match the devpath of the event device\&.
+.RE
+.PP
+\fBKERNEL\fR
+.RS 4
+Match the name of the event device\&.
+.RE
+.PP
+\fBNAME\fR
+.RS 4
+Match the name of a network interface\&. It can be used once the NAME key has been set in one of the preceding rules\&.
+.RE
+.PP
+\fBSYMLINK\fR
+.RS 4
+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\&.
+.RE
+.PP
+\fBSUBSYSTEM\fR
+.RS 4
+Match the subsystem of the event device\&.
+.RE
+.PP
+\fBDRIVER\fR
+.RS 4
+Match the driver name of the event device\&. Only set this key for devices which are bound to a driver at the time the event is generated\&.
+.RE
+.PP
+\fBATTR{\fR\fB\fIfilename\fR\fR\fB}\fR
+.RS 4
+Match sysfs attribute values of the event device\&. Trailing whitespace in the attribute values is ignored unless the specified match value itself contains trailing whitespace\&.
+.RE
+.PP
+\fBKERNELS\fR
+.RS 4
+Search the devpath upwards for a matching device name\&.
+.RE
+.PP
+\fBSUBSYSTEMS\fR
+.RS 4
+Search the devpath upwards for a matching device subsystem name\&.
+.RE
+.PP
+\fBDRIVERS\fR
+.RS 4
+Search the devpath upwards for a matching device driver name\&.
+.RE
+.PP
+\fBATTRS{\fR\fB\fIfilename\fR\fR\fB}\fR
+.RS 4
+Search the devpath upwards for a device with matching sysfs attribute values\&. If multiple
+\fBATTRS\fR
+matches are specified, all of them must match on the same device\&. Trailing whitespace in the attribute values is ignored unless the specified match value itself contains trailing whitespace\&.
+.RE
+.PP
+\fBTAGS\fR
+.RS 4
+Search the devpath upwards for a device with matching tag\&.
+.RE
+.PP
+\fBENV{\fR\fB\fIkey\fR\fR\fB}\fR
+.RS 4
+Match against a device property value\&.
+.RE
+.PP
+\fBTAG\fR
+.RS 4
+Match against a device tag\&.
+.RE
+.PP
+\fBTEST{\fR\fB\fIoctal mode mask\fR\fR\fB}\fR
+.RS 4
+Test the existence of a file\&. An octal mode mask can be specified if needed\&.
+.RE
+.PP
+\fBPROGRAM\fR
+.RS 4
+Execute a program to determine whether there is a match; the key is true if the program returns successfully\&. The device properties are made available to the executed program in the environment\&. The program\*(Aqs stdout is available in the RESULT key\&.
+.sp
+This can only be used for very short\-running foreground tasks\&. For details see
+\fBRUN\fR\&.
+.RE
+.PP
+\fBRESULT\fR
+.RS 4
+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\&.
+.RE
+.PP
+Most of the fields support shell\-style pattern matching\&. The following pattern characters are supported:
+.PP
+*
+.RS 4
+Matches zero or more characters\&.
+.RE
+.PP
+?
+.RS 4
+Matches any single character\&.
+.RE
+.PP
+[]
+.RS 4
+Matches any single character specified within the brackets\&. For example, the pattern string \*(Aqtty[SR]\*(Aq would match either \*(AqttyS\*(Aq or \*(AqttyR\*(Aq\&. Ranges are also supported via the \*(Aq\-\*(Aq character\&. For example, to match on the range of all digits, the pattern [0\-9] could be used\&. If the first character following the \*(Aq[\*(Aq is a \*(Aq!\*(Aq, any characters not enclosed are matched\&.
+.RE
+.PP
+The following keys can get values assigned:
+.PP
+\fBNAME\fR
+.RS 4
+The name to use for a network interface\&. The name of a device node cannot be changed by udev, only additional symlinks can be created\&.
+.RE
+.PP
+\fBSYMLINK\fR
+.RS 4
+The name of a symlink targeting the node\&. Every matching rule adds this value to the list of symlinks to be created\&.
+.sp
+The set of characters to name a symlink is limited\&. Allowed characters are [0\-9A\-Za\-z#+\-\&.:=@_/], valid utf8 character sequences, and "\ex00" hex encoding\&. All other characters are replaced by a \*(Aq_\*(Aq character\&.
+.sp
+Multiple symlinks may be specified by separating the names by the space character\&. In case multiple devices claim the same name, the link always points to the device with the highest link_priority\&. If the current device goes away, the links are re\-evaluated and the device with the next highest link_priority becomes the owner of the link\&. If no link_priority is specified, the order of the devices (and which one of them owns the link) is undefined\&.
+.sp
+Symlink names must never conflict with the kernel\*(Aqs default device node names, as that would result in unpredictable behavior\&.
+.RE
+.PP
+\fBOWNER\fR, \fBGROUP\fR, \fBMODE\fR
+.RS 4
+The permissions for the device node\&. Every specified value overrides the compiled\-in default value\&.
+.RE
+.PP
+\fBATTR{\fR\fB\fIkey\fR\fR\fB}\fR
+.RS 4
+The value that should be written to a sysfs attribute of the event device\&.
+.RE
+.PP
+\fBENV{\fR\fB\fIkey\fR\fR\fB}\fR
+.RS 4
+Set a device property value\&. Property names with a leading \*(Aq\&.\*(Aq are neither stored in the database nor exported to events or external tools (run by, say, the PROGRAM match key)\&.
+.RE
+.PP
+\fBTAG\fR
+.RS 4
+Attach a tag to a device\&. This is used to filter events for users of libudev\*(Aqs monitor functionality, or to enumerate a group of tagged devices\&. The implementation can only work efficiently if only a few tags are attached to a device\&. It is only meant to be used in contexts with specific device filter requirements, and not as a general\-purpose flag\&. Excessive use might result in inefficient event handling\&.
+.RE
+.PP
+\fBRUN{\fR\fB\fItype\fR\fR\fB}\fR
+.RS 4
+Add a program to the list of programs to be executed after processing all the rules for a specific event, depending on
+type:
+.PP
+program
+.RS 4
+Execute an external program specified as the assigned value\&. If no absolute path is given, the program is expected to live in /usr/lib/udev, otherwise the absolute path must be specified\&.
+.sp
+This is the default if no
+\fItype\fR
+is specified\&.
+.RE
+.PP
+builtin
+.RS 4
+As
+\fBprogram\fR, but use one of the built\-in programs rather than an external one\&.
+.RE
+.sp
+The program name and following arguments are separated by spaces\&. Single quotes can be used to specify arguments with spaces\&.
+.sp
+This can only be used for very short\-running foreground tasks\&. Running an event process for a long period of time may block all further events for this or a dependent device\&.
+.sp
+Starting daemons or other long running processes is not appropriate for udev; the forked processes, detached or not, will be unconditionally killed after the event handling has finished\&.
+.RE
+.PP
+\fBLABEL\fR
+.RS 4
+A named label to which a GOTO may jump\&.
+.RE
+.PP
+\fBGOTO\fR
+.RS 4
+Jumps to the next LABEL with a matching name\&.
+.RE
+.PP
+\fBIMPORT{\fR\fB\fItype\fR\fR\fB}\fR
+.RS 4
+Import a set of variables as device properties, depending on
+type:
+.PP
+program
+.RS 4
+Execute an external program specified as the assigned value and import its output, which must be in environment key format\&. Path specification, command/argument separation, and quoting work like in
+\fBRUN\fR\&.
+.RE
+.PP
+builtin
+.RS 4
+As
+\fBprogram\fR, but use one of the built\-in programs rather than an external one\&.
+.RE
+.PP
+file
+.RS 4
+Import a text file specified as the assigned value, the content of which must be in environment key format\&.
+.RE
+.PP
+db
+.RS 4
+Import a single property specified as the assigned value from the current device database\&. This works only if the database is already populated by an earlier event\&.
+.RE
+.PP
+cmdline
+.RS 4
+Import a single property from the kernel command line\&. For simple flags the value of the property is set to \*(Aq1\*(Aq\&.
+.RE
+.PP
+parent
+.RS 4
+Import the stored keys from the parent device by reading the database entry of the parent device\&. The value assigned to
+\fBIMPORT{parent}\fR
+is used as a filter of key names to import (with the same shell\-style pattern matching used for comparisons)\&.
+.RE
+.sp
+This can only be used for very short\-running foreground tasks\&. For details see
+\fBRUN\fR\&.
+.RE
+.PP
+\fBWAIT_FOR\fR
+.RS 4
+Wait for a file to become available or until a timeout of 10 seconds expires\&. The path is relative to the sysfs device; if no path is specified, this waits for an attribute to appear\&.
+.RE
+.PP
+\fBOPTIONS\fR
+.RS 4
+Rule and device options:
+.PP
+\fBlink_priority=\fR\fB\fIvalue\fR\fR
+.RS 4
+Specify the priority of the created symlinks\&. Devices with higher priorities overwrite existing symlinks of other devices\&. The default is 0\&.
+.RE
+.PP
+\fBevent_timeout=\fR
+.RS 4
+Number of seconds an event waits for operations to finish before giving up and terminating itself\&.
+.RE
+.PP
+\fBstring_escape=\fR\fB\fInone|replace\fR\fR
+.RS 4
+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\&.
+.RE
+.PP
+\fBstatic_node=\fR
+.RS 4
+Apply the permissions specified in this rule to the static device node with the specified name\&. Static device node creation can be requested by kernel modules\&. These nodes might not have a corresponding kernel device at the time udevd is started; they can trigger automatic kernel module loading\&.
+.RE
+.PP
+\fBwatch\fR
+.RS 4
+Watch the device node with inotify; when the node is closed after being opened for writing, a change uevent is synthesized\&.
+.RE
+.PP
+\fBnowatch\fR
+.RS 4
+Disable the watching of a device node with inotify\&.
+.RE
+.RE
+.PP
+The
+\fBNAME\fR,
+\fBSYMLINK\fR,
+\fBPROGRAM\fR,
+\fBOWNER\fR,
+\fBGROUP\fR,
+\fBMODE\fR
+and
+\fBRUN\fR
+fields support simple string substitutions\&. The
+\fBRUN\fR
+substitutions are performed after all rules have been processed, right before the program is executed, allowing for the use of device properties set by earlier matching rules\&. For all other fields, substitutions are performed while the individual rule is being processed\&. The available substitutions are:
+.PP
+\fB$kernel\fR, \fB%k\fR
+.RS 4
+The kernel name for this device\&.
+.RE
+.PP
+\fB$number\fR, \fB%n\fR
+.RS 4
+The kernel number for this device\&. For example, \*(Aqsda3\*(Aq has kernel number of \*(Aq3\*(Aq
+.RE
+.PP
+\fB$devpath\fR, \fB%p\fR
+.RS 4
+The devpath of the device\&.
+.RE
+.PP
+\fB$id\fR, \fB%b\fR
+.RS 4
+The name of the device matched while searching the devpath upwards for
+\fBSUBSYSTEMS\fR,
+\fBKERNELS\fR,
+\fBDRIVERS\fR
+and
+\fBATTRS\fR\&.
+.RE
+.PP
+\fB$driver\fR
+.RS 4
+The driver name of the device matched while searching the devpath upwards for
+\fBSUBSYSTEMS\fR,
+\fBKERNELS\fR,
+\fBDRIVERS\fR
+and
+\fBATTRS\fR\&.
+.RE
+.PP
+\fB$attr{\fR\fB\fIfile\fR\fR\fB}\fR, \fB%s{\fR\fB\fIfile\fR\fR\fB}\fR
+.RS 4
+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, and a previous KERNELS, SUBSYSTEMS, DRIVERS, or ATTRS test selected a parent device, then the attribute from that parent device is used\&.
+.sp
+If the attribute is a symlink, the last element of the symlink target is returned as the value\&.
+.RE
+.PP
+\fB$env{\fR\fB\fIkey\fR\fR\fB}\fR, \fB%E{\fR\fB\fIkey\fR\fR\fB}\fR
+.RS 4
+A device property value\&.
+.RE
+.PP
+\fB$major\fR, \fB%M\fR
+.RS 4
+The kernel major number for the device\&.
+.RE
+.PP
+\fB$minor\fR, \fB%m\fR
+.RS 4
+The kernel minor number for the device\&.
+.RE
+.PP
+\fB$result\fR, \fB%c\fR
+.RS 4
+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:
+\fB%c{N}\fR\&. If the number is followed by the \*(Aq+\*(Aq character, this part plus all remaining parts of the result string are substituted:
+\fB%c{N+}\fR
+.RE
+.PP
+\fB$parent\fR, \fB%P\fR
+.RS 4
+The node name of the parent device\&.
+.RE
+.PP
+\fB$name\fR
+.RS 4
+The current name of the device\&. If not changed by a rule, it is the name of the kernel device\&.
+.RE
+.PP
+\fB$links\fR
+.RS 4
+A space\-separated list of the current symlinks\&. The value is only set during a remove event or if an earlier rule assigned a value\&.
+.RE
+.PP
+\fB$root\fR, \fB%r\fR
+.RS 4
+The udev_root value\&.
+.RE
+.PP
+\fB$sys\fR, \fB%S\fR
+.RS 4
+The sysfs mount point\&.
+.RE
+.PP
+\fB$devnode\fR, \fB%N\fR
+.RS 4
+The name of the device node\&.
+.RE
+.PP
+%%
+.RS 4
+The \*(Aq%\*(Aq character itself\&.
+.RE
+.PP
+$$
+.RS 4
+The \*(Aq$\*(Aq character itself\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBudevd\fR(8),
+\fBudevadm\fR(8)