X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=udev.8;h=24ff4e28a964fca2ea698282ffaff7fe8ea1a4f9;hp=6ee68d795e5a428dc6fe1d19414be03b6b0f0488;hb=2bd07cf29b30b424d4b5a17882d0cab0b235153b;hpb=2ebcaa235fe2b82a844ae19daecb0c996375fc1b diff --git a/udev.8 b/udev.8 index 6ee68d795..24ff4e28a 100644 --- a/udev.8 +++ b/udev.8 @@ -3,14 +3,34 @@ udev \- Linux configurable dynamic device naming support .SH SYNOPSIS .BI udev " hotplug-subsystem" -.br +.P +The environment must provide the following variables: +.TP +.B ACTION +.IR add " or " remove +signifies the connection or disconnection of a device. +.TP +.B DEVPATH +The sysfs devpath of the device without the mountpoint but a leading slash. +.P +Additional optional environment variables are: +.TP +.B UDEV_CONFIG_FILE +Overrides the default location of the .B udev -.RI "[-q " query_type " -p " sysfs_path "] [-drVh]" +config file. +.TP +.B UDEV_NO_SLEEP +The default behavior of +.B udev +is to wait until all the sysfs files of the device chain are populated. If set +.B udev +will continue, regardless of the state of the device representation. .SH "DESCRIPTION" .B udev creates or removes device node files usually located in the /dev directory. -Its goal is to provide a dynamic device directory that contains only the files -for devices that are actually present. +It provides a dynamic device directory that contains only the files for +devices that are actually present. .P As part of the .B hotplug @@ -29,37 +49,6 @@ maintains a database for devices present on the system. On device removal, .B udev queries its database for the name of the device file to be deleted. -.SH "OPTIONS" -.B udev -normally is called by -.B hotplug -with the subsystem as argument and various environment variables set. -.br -It may also called with the following options: -.TP -.B -V -Print the version information. -.TP -.B -r -Print the the -.B udev_root -directory. When used in conjunction with a query for the node name, the -.B udev_root -will be prepended. -.TP -.BI -q " query_type" -Query the database for specified value of a created device node. -Valid types are: -.BR name ", " symlink ", " owner " or " group . -.TP -.BI -p " sysfs_path" -Specify the sysfs path needed for the query. -.TP -.B -d -Dump the whole database. -.TP -.B -h -Print help text. .SH "CONFIGURATION" All .B udev @@ -69,7 +58,7 @@ lines, and lines beginning with a '#' will be ignored. .B udev expects its main configuration file at -.I /etc/udev/udev.conf. +.IR /etc/udev/udev.conf . The file consists of a set of variables and values that allow the user to override default udev values. The current set of variables that can be overridden in this file is: @@ -77,24 +66,46 @@ overridden in this file is: .B udev_root This is the where in the filesystem to place the device nodes. The default value for this is -.I /udev/ +.IR /udev/ . .TP .B udev_db The name and location of the udev database. The default value for this is -.I /udev/.udev.tdb +.IR /udev/.udev.tdb . .TP .B udev_rules This is the location of the udev rules file. The default value for this is -.I /etc/udev/udev.rules +.IR /etc/udev/udev.rules . +If a directory is specified, the whole directory is +scanned for files ending with +.I .rules +and all rule files are read in lexical order. .TP .B udev_permissions -This is the location of the udev permission file. The default value for this is -.I /etc/udev/udev.permissions +This is the location of the udev permission file. The default value for this is +.IR /etc/udev/udev.permissions . +If a directory is specified, the whole directory is scanned for files ending with +.I .permissions +and all permission files are read in lexical order. +.TP +.B udev_log +If you want udev to log some information to the syslog for every node created or +removed. The default value for this is +.IR yes . .TP .B default_mode This is the default mode for all nodes that have no explicit match in the permissions file. The default value for this is -.I 0666 +.IR 0666 . +.TP +.B default_owner +This is the default owner for all nodes that have no explicit match in the +permissions file. The default value for this is +.IR root . +.TP +.B default_group +This is the default group for all nodes that have no explicit match in the +permissions file. The default value for this is +.IR root . .br .P .RI "A sample " udev.conf " might look like this: @@ -106,15 +117,27 @@ udev_root="/udev/" # udev_db - The name and location of the udev database. udev_db="/udev/.udev.tdb" -# udev_rules - The name and location of the udev rules file -udev_rules="/etc/udev/udev.rules" +# udev_rules - The location of the directory where to look for files + which names ending with .rules +udev_rules="/etc/udev/" # udev_permissions - The name and location of the udev permission file udev_permissions="/etc/udev/udev.permissions" +# udev_log - set to "yes" if you want logging, else "no" +udev_log="yes" + # default_mode - set the default mode for all nodes that have no # explicit match in the permissions file default_mode="0666" + +# default_owner - set the default owner for all nodes that have no +# explicit match in the permissions file +default_owner="root" + +# default_group - set the default group for all nodes that have no +# explicit match in the permissions file +default_group="root" .fi .P The rules for udev to use when naming devices may specified at @@ -128,16 +151,15 @@ file. Every line in the rules file defines the mapping between device attributes and the device file name. One ore more keys are specified to match a rule with the current device. If all keys are matching, the rule will be applied -and the name is used for the device node. One or more optional symlinks -targeting the node may be specified. +and the name is used for the device node. .br If no matching rule is found, the default kernel device name is used. .P -The line format is: +Every rule consists of a list a comma separated fields: .sp -.I key,[key,...] name [, symlink] +.IR "key " ,[ "key " ,...] " name " [, " symlink" ] .sp -where keys are: +where possible fields are: .TP .B BUS Match the bus type of the device. @@ -152,13 +174,20 @@ Match the device number on the bus, like PCI bus id. .B PLACE Match the topological position on bus, like physical port of USB device .TP -.BI SYSFS_ filename +.BI SYSFS{ filename } Match sysfs device attribute like label, vendor, USB serial number, SCSI UUID or file system label. Up to 5 different sysfs files can be checked, with all of the values being required in order to match the rule. +.br +Trailing whitespace characters in the sysfs attribute value are ignored, if +the key doesn't have any trailing whitespace characters by itself. .TP .B PROGRAM Call external program. This key is valid if the program returns successful. +The environment variables of +.B udev +are also available for the program. +.br The string returned by the program may additionally matched with the .B RESULT key. @@ -169,13 +198,35 @@ Match the returned string of the last call. This key may used in any following rule after a .B PROGRAM call. +.TP +.B NAME +The name of the node to be created. +.br +If given with the attribute +.BR NAME{ all_partitions } +it will create all 15 partitions of a blockdevice. +This may be useful for removable media devices. +.TP +.B SYMLINK +The name of a symlink targeting the node. Multiple symlinks may be +specified by separating the names by the space character. +.br +If both the name and the symlink fields are omitted or its +values empty, the device will be ignored and no node will be created. +.br +If only the symlink field is given and the name field is omitted, +the rule will not be applied immediatly, but the symlink field is added +to the symlink list of the rule which will create the node. +This makes it possible to specify additional symlinks in a possibly +separate rules file, while the device nodes are maintained by the +distribution provided rules file. .P .RB "The " NAME " ," SYMLINK " and " PROGRAM fields support simple printf-like string substitution: .TP .B %n The "kernel number" of the device. -for example, 'sda3' has a "kernel number" of '3' +For example, 'sda3' has a "kernel number" of '3'. .TP .B %k The "kernel name" for the device. @@ -190,13 +241,26 @@ The kernel minor number for the device. The bus id for the device. .TP .B %c -The CALLOUT program returned string. -(This does not work within the PROGRAM field for the obvious reason.) +The +.B PROGRAM +returned string. +(This does not work within the +.B PROGRAM +field for the obvious reason.) +.br +A single part of the string, separated by the space character +my be selected by specifying the part number as a attribute: +.BI %c{ part } .TP -.B %D -Use the devfs style disk name for this device. -For partitions, this will result in 'part%n' -If this is not a partition, it will result in 'disc'. +.BI %s{ filename } +The content of a sysfs attribute. +.TP +.B %% +The '%' character itself. +.P +The count of charcters to insert may be limited by specifying +the format length value. For example, '%3s{file}' will only insert +the first three characters of the sysfs attribute. .P .RI "A sample " udev.rules " might look like this:" .sp @@ -205,10 +269,10 @@ If this is not a partition, it will result in 'disc'. BUS="scsi", PROGRAM="/sbin/scsi_id", RESULT="OEM 0815", NAME="disk1" # USB printer to be called lp_color -BUS="usb", SYSFS_serial="W09090207101241330", NAME="lp_color" +BUS="usb", SYSFS{serial}="W09090207101241330", NAME="lp_color" # SCSI disk with a specific vendor and model number is to be called boot -BUS="scsi", SYSFS_vendor="IBM", SYSFS_model="ST336", NAME="boot%n" +BUS="scsi", SYSFS{vendor}="IBM", SYSFS{model}="ST336", NAME="boot%n" # sound card with PCI bus id 00:0b.0 to be called dsp BUS="pci", ID="00:0b.0", NAME="dsp" @@ -220,7 +284,7 @@ BUS="usb", PLACE="2.3", NAME="mouse1" KERNEL="ttyUSB1", NAME="pda", SYMLINK="palmtop handheld" # multiple USB webcams with symlinks to be called webcam0, webcam1, ... -BUS="usb", SYSFS_model="XV3", NAME="video%n", SYMLINK="webcam%n" +BUS="usb", SYSFS{model}="XV3", NAME="video%n", SYMLINK="webcam%n" .fi .P Permissions and ownership for the created device files may specified at @@ -234,11 +298,6 @@ file. Every line lists a device name followed by owner, group and permission mode. All values are separated by colons. The name field may contain a pattern to apply the values to a whole class of devices. -.br -If -.B udev -was built using klibc or is used before the user database is accessible (e.g. -.BR initrd "(4)), only numeric owner and group values may be used." .sp .RI "A sample " udev.permissions " might look like this:" .sp @@ -250,6 +309,17 @@ video*:root:video:0660 dsp1:::0666 .fi .P +The value +.I $local +can be substituted for a specific username. In that case, udev will determine +the current local user at the time of device node creation and substitute +that username as the owner of the new device node. This is useful, for +example, to let hot-plugged devices, such as cameras, be owned by the user at +the current console. Note that if no user is currently logged in, or if udev +otherwise fails to determine a current user, the +.I default_owner +value is used in lieu. +.P A number of different fields in the above configuration files support a simple form of shell style pattern matching. It supports the following pattern characters: .TP @@ -262,8 +332,8 @@ Matches any single character, but does not match zero characters. .B [ ] 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 +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 '!' then any character not enclosed is matched. .SH "FILES" .nf @@ -273,10 +343,12 @@ following the '[' is a '!' then any character not enclosed is matched. .fi .LP .SH "SEE ALSO" +.BR udevinfo (8), +.BR udevd (8), .BR hotplug (8) .PP The -.I http://linux-hotplug.sourceforge.net/ +.I http://linux\-hotplug.sourceforge.net/ web site. .SH AUTHORS .B udev