[PATCH] implement printf-like placeholder support for NAME

[elogind.git] / udev.8

diff --git a/udev.8 b/udev.8
index 771ecfa454915c2fd3b4eb13478837ff853923f9..79b74bf659736f850d368aac0e9a682d0068728a 100644 (file)
--- a/udev.8
+++ b/udev.8
@@ -2,66 +2,110 @@
 .SH NAME
 udev \- Linux configurable dynamic device naming support
 .SH SYNOPSIS
 .SH NAME
 udev \- Linux configurable dynamic device naming support
 .SH SYNOPSIS

-.B udev
+.BI udev " hotplug-subsystem"

 .SH "DESCRIPTION"
 .B udev
 creates or removes device node files usually located in the /dev directory.
 .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.
+.P

 As part of the
 .B hotplug
 subsystem,
 .B udev
 As part of the
 .B hotplug
 subsystem,
 .B udev

-is exectuted if a kernel device is added or removed from the system.
-.P
+is executed if a kernel device is added or removed from the system.

 On device creation,
 .B udev
 On device creation,
 .B udev

-reads the sysfs directory of the given device, to collect device attributes
+reads the sysfs directory of the given device to collect device attributes

 like label, serial number or bus device number.
 like label, serial number or bus device number.

-These attributes are passed as a key to the namedev subsystem
-to receive a unique name for device file creation.
-namedev maintains a database for devices present on the system.
-.P
+These attributes are treated as a key 
+to determine a unique name for device file creation.
+.B udev
+maintains a database for devices present on the system.
+.br

 On device removal,
 .B udev
 On device removal,
 .B udev

-queries the namedev database for the name of the device file to delete.
-.P
-namedev expects its configuration at
-.I /etc/udev/namedev.config.
+queries the internal database for the name of the device file to be deleted.
+.SH "CONFIGURATION"
+.B udev
+expects its configuration at
+.I /etc/udev/udev.config.

 The file consists of a set of lines. All empty lines and
 lines beginning with a '#' will be ignored.
 .br
 The file consists of a set of lines. All empty lines and
 lines beginning with a '#' will be ignored.
 .br

-Every line defines the mapping between device attributes and the name of
-the device file. It starts with a keyword defining the method for
-overriding the default kernel naming scheme, followed by a list
-of keys and ends with the definition of the filename for the device.
+Every line defines the mapping between device attributes and the device file
+name. It starts with a keyword defining the method used to match, followed by
+one ore more keys to compare and the filename for the device. If no matching
+configuration is found, the default kernel device name is used.
+.P
+The line format is:
+.RS
+.sp
+.I method, key,[key,...] name
+.sp
+.RE
+where valid methods with corresponding keys are:

 .TP
 .B LABEL
 device label or serial number, like USB serial number, SCSI UUID or
 file system label
 .TP
 .B LABEL
 device label or serial number, like USB serial number, SCSI UUID or
 file system label

+.br
+keys: \fBBUS\fP, \fIsysfs_attribute\fP

 .TP
 .B NUMBER
 device number on the bus, like PCI bus id
 .TP
 .B NUMBER
 device number on the bus, like PCI bus id

+.br
+keys: \fBBUS\fP, \fBID\fP

 .TP
 .B TOPOLOGY
 device position on bus, like physical port of USB device
 .TP
 .B TOPOLOGY
 device position on bus, like physical port of USB device

+.br
+keys: \fBBUS\fP, \fBPLACE\fP

 .TP
 .B REPLACE
 string replacement of the kernel device name
 .TP
 .B REPLACE
 string replacement of the kernel device name

+.br
+key: \fBKERNEL_NAME\fP
+.TP
+.B CALLOUT
+calling external program, that returns a string to match
+.br
+keys: \fBBUS\fP, \fBPROGRAM\fP, \fBID\fP

 .P
 .P

-If no matching configuration is found, the default kernel device name is used.
-.SH "EXAMPLE"
+A sample \fIudev.conf\fP might look like this:
+.sp

 .nf
 # USB printer to be called lp_color
 LABEL, BUS="usb", serial="W09090207101241330", NAME="lp_color"
 
 # sound card with PCI bus id 00:0b.0 to be called dsp
 .nf
 # USB printer to be called lp_color
 LABEL, BUS="usb", serial="W09090207101241330", NAME="lp_color"
 
 # sound card with PCI bus id 00:0b.0 to be called dsp

-NUMBER, BUS="pci", id="00:0b.0", NAME="dsp"
+NUMBER, BUS="pci", ID="00:0b.0", NAME="dsp"

 
 # USB mouse at third port of the second hub to be called mouse1
 
 # USB mouse at third port of the second hub to be called mouse1

-TOPOLOGY, BUS="usb", place="2.3", NAME="mouse1"
+TOPOLOGY, BUS="usb", PLACE="2.3", NAME="mouse1"

 
 # ttyUSB1 should always be called pda
 REPLACE, KERNEL="ttyUSB1", NAME="pda"
 
 # ttyUSB1 should always be called pda
 REPLACE, KERNEL="ttyUSB1", NAME="pda"

+
+# if /sbin/scsi_id returns "OEM 0815" device will be called disk1
+CALLOUT, PROGRAM="/sbin/scsi_id" BUS="scsi", ID="OEM 0815" NAME="disk1"
+.fi
+.P
+Permissions and ownership for the created device files may specified at
+.I /etc/udev/udev.permissions.
+The file consists of a set of lines. All empty lines and
+lines beginning with a '#' will be ignored.
+.br
+Every line lists a device name followed by owner, group and permission mode. All values are separated by colons.
+.sp
+A sample \fIudev.permissions\fP might look like this:
+.sp
+.nf
+#name:user:group:mode
+ttyUSB1:root:uucp:0666
+dsp1:::0666

 .fi
 .fi

+

 .SH "FILES"
 .nf
 .ft B
 .SH "FILES"
 .nf
 .ft B


@@ -72,11 +116,12 @@ REPLACE, KERNEL="ttyUSB1", NAME="pda"
 .fi
 .LP
 .SH "SEE ALSO"
 .fi
 .LP
 .SH "SEE ALSO"

-.B hotplug (8)
+.BR hotplug (8)

 .PP
 The
 .I http://linux-hotplug.sourceforge.net/
 web site.
 .SH AUTHORS
 .PP
 The
 .I http://linux-hotplug.sourceforge.net/
 web site.
 .SH AUTHORS

-udev was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from
+.B udev
+was developed by Greg Kroah-Hartman <greg@kroah.com> with much help from

 Dan Stekloff <dsteklof@us.ibm.com> and many others.
 Dan Stekloff <dsteklof@us.ibm.com> and many others.