<refentry>
<refentryinfo>
<title>udev</title>
- <date>August 2005</date>
<productname>udev</productname>
</refentryinfo>
<refmeta>
<refentrytitle>udev</refentrytitle>
<manvolnum>7</manvolnum>
- <refmiscinfo class="version"></refmiscinfo>
</refmeta>
<refnamediv>
<refname>udev</refname>
- <refpurpose>dynamic device management</refpurpose>
+ <refpurpose>Linux dynamic device management</refpurpose>
</refnamediv>
<refsect1><title>DESCRIPTION</title>
- <para>udev provides a dynamic device directory containing only the files for
- actually present devices. It creates or removes device node files in the
- <filename>/dev</filename> directory, or it renames network interfaces.</para>
-
- <para>Usually udev runs as <citerefentry><refentrytitle>udevd</refentrytitle>
- <manvolnum>8</manvolnum></citerefentry> and receives uevents directly from the
- kernel if a device is added or removed from the system.</para>
-
- <para>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.</para>
+ <para>udev supplies the system software with device events, manages permissions
+ of device nodes and may create additional symlinks in the <filename>/dev</filename>
+ 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.</para>
+
+ <para>The udev daemon <citerefentry><refentrytitle>udevd</refentrytitle>
+ <manvolnum>8</manvolnum></citerefentry> 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 information
+ to be used to create meaningful symlink names.</para>
+
+ <para>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 are provided by the library libudev.</para>
</refsect1>
<refsect1><title>CONFIGURATION</title>
If all match keys are matching against its value, the rule gets applied and the
assign keys get the specified value assigned.</para>
- <para>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.</para>
+ <para>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.</para>
- <para>A rule may consist of a list of one or more key value pairs separated by
+ <para>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:</para>
<variablelist>
<varlistentry>
<term><option>!=</option></term>
<listitem>
- <para>Compare for non-equality.</para>
+ <para>Compare for inequality.</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>SYMLINK</option></term>
+ <listitem>
+ <para>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.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>SUBSYSTEM</option></term>
<listitem>
<varlistentry>
<term><option>ATTR{<replaceable>filename</replaceable>}</option></term>
<listitem>
- <para>Match sysfs attribute values of the event device. Up to five
- <option>ATTR</option> keys can be specified per rule. Trailing
+ <para>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. Depending on the type
- of operator, this key is also used to set the value of a sysfs attribute.
+ value does not contain trailing whitespace itself.
</para>
</listitem>
</varlistentry>
<term><option>ATTRS{<replaceable>filename</replaceable>}</option></term>
<listitem>
<para>Search the devpath upwards for a device with matching sysfs attribute values.
- Up to five <option>ATTRS</option> keys can be specified per rule, but all of them
+ If multiple <option>ATTRS</option> 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.</para>
</listitem>
<varlistentry>
<term><option>ENV{<replaceable>key</replaceable>}</option></term>
<listitem>
- <para>Match against the value of an environment variable. Up to five <option>ENV</option>
- keys can be specified per rule. Depending on the type of operator, this key is also used
- to export a variable to the environment.</para>
+ <para>Match against a device property value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>TAG</option></term>
+ <listitem>
+ <para>Match against a device tag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>PROGRAM</option></term>
<listitem>
- <para>Execute external program. The key is true, if the program returns
- with exit code zero. The whole event environment is available to the
- executed program. The program's output printed to stdout, is available in
- the RESULT key.</para>
+ <para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>NAME</option></term>
<listitem>
- <para>The name of the node to be created, or the name the network interface
- should be renamed to. Only one rule can set the node name, all later rules with
- a NAME key will be ignored.</para>
+ <para>The name, a network interface should be renamed to. Or as
+ a temporary workaraound, the name a device node should be named.
+ Usually the kernel provides the defined node name, or even creates
+ and removes the node before udev even receives any event. Changing
+ the node name from the kernel's default creates inconsistencies
+ and is not supported. If the kernel and NAME specify different names,
+ an error will be logged. Udev is only expected to handle device node
+ permissions and to create additional symlinks, not to change
+ kernel-provided device node names. Instead of renaming a device node,
+ SYMLINK should be used. Symlink names must never conflict with
+ device node names, it will result in unpredictable behavior.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>SYMLINK</option></term>
<listitem>
- <para>The name of a symlink targeting the node. Every matching rule can 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.</para>
+ <para>The name of a symlink targeting the node. Every matching rule will add
+ this value to the list of symlinks to be created. Multiple symlinks may be
+ specified by separating the names by the space character. In case multiple
+ devices claim the same name, the link will always point to the device with
+ the highest link_priority. If the current device goes away, the links will
+ be re-evaluated and the device with the next highest link_priority will own
+ the link. If no link_priority is specified, the order of the devices, and
+ which one of them will own the link, is undefined. Claiming the same name for
+ a symlink, which is or might be used for a device node, may result in
+ unexpected behavior and is not supported.
+ </para>
</listitem>
</varlistentry>
<term><option>ATTR{<replaceable>key</replaceable>}</option></term>
<listitem>
<para>The value that should be written to a sysfs attribute of the
- event device. Depending on the type of operator, this key is also
- used to match against the value of a sysfs attribute.</para>
+ event device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>ENV{<replaceable>key</replaceable>}</option></term>
<listitem>
- <para>Export a variable to the environment. Depending on the type of operator,
- this key is also to match against an environment variable.</para>
+ <para>Set a device property value. Property names with a leading '.'
+ are not stored in the database or exported to external tool or events.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>TAG</option></term>
+ <listitem>
+ <para>Attach a tag to a device. This is used to filter events for users
+ of libudev's 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.</para>
</listitem>
</varlistentry>
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.</para>
- <para>If the specifiefd string starts with
- <option>socket:<replaceable>path</replaceable></option>, 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.</para>
+ detached from the event process itself. If the option
+ <option>RUN{<replaceable>fail_event_on_error</replaceable>}</option> is
+ specified, and the executed program returns non-zero, the event will be
+ marked as failed for a possible later handling.</para>
+ <para>If no absolute path is given, the program is expected to live in
+ <filename>/lib/udev</filename>, otherwise the absolute path must be
+ specified. Program name and arguments are separated by spaces. Single quotes
+ can be used to specify arguments with spaces.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>IMPORT{<replaceable>type</replaceable>}</option></term>
<listitem>
- <para>Import a set of variables into the event environment,
+ <para>Import a set of variables as device properties,
depending on <replaceable>type</replaceable>:</para>
<variablelist>
<varlistentry>
<term><option>program</option></term>
<listitem>
<para>Execute an external program specified as the assigned value and
- import its output, which must be in environment key format.</para>
+ import its output, which must be in environment key
+ format. Path specification, command/argument separation,
+ and quoting work like in <option>RUN</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
environment key format.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>db</option></term>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><option>parent</option></term>
<listitem>
<varlistentry>
<term><option>WAIT_FOR</option></term>
<listitem>
- <para>Wait for a file to become available.</para>
+ <para>Wait for a file to become available or until a 10
+ seconds timeout expires.</para>
</listitem>
</varlistentry>
<listitem>
<para>Rule and device options:</para>
<variablelist>
- <varlistentry>
- <term><option>last_rule</option></term>
- <listitem>
- <para>Stops further rules application. No later rules will have
- any effect.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>ignore_device</option></term>
- <listitem>
- <para>Ignore this event completely.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>ignore_remove</option></term>
- <listitem>
- <para>Do not remove the device node when the device goes away. This may be
- useful as a workaround for broken device drivers.</para>
- </listitem>
- </varlistentry>
<varlistentry>
<term><option>link_priority=<replaceable>value</replaceable></option></term>
<listitem>
priorities overwrite existing symlinks of other devices. The default is 0.</para>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>all_partitions</option></term>
- <listitem>
- <para>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.</para>
- </listitem>
- </varlistentry>
<varlistentry>
<term><option>event_timeout=</option></term>
<listitem>
with this option.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>watch</option></term>
+ <listitem>
+ <para>Watch the device node with inotify, when closed after being opened for
+ writing, a change uevent will be synthesised.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
</listitem>
</varlistentry>
<option>OWNER</option>, <option>GROUP</option>, <option>MODE</option> and <option>RUN</option>
fields support simple printf-like string substitutions. The <option>RUN</option>
format chars gets applied after all rules have been processed, right before the program
- is executed. It allows the use of the complete environment set by earlier matching
+ 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:</para>
<variablelist>
<varlistentry>
<term><option>$env{<replaceable>key</replaceable>}</option>, <option>%E{<replaceable>key</replaceable>}</option></term>
<listitem>
- <para>The value of an environment variable.</para>
+ <para>A device property value.</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
</variablelist>
- <para>The count of characters to be substituted may be limited by specifying
- the format length value. For example, '%3s{file}' will only
- insert the first three characters of the sysfs attribute</para>
</refsect2>
</refsect1>
~ianmdlvl / elogind.git / blobdiff