chiark / gitweb /
reset process priority before executing RUN+=
[elogind.git] / udev / udev.xml
index 4c35e197911ee16b7b30e10d3ba8f99f537a4494..678023c373f444aef087447b9cf9619c0ba70cea 100644 (file)
@@ -8,35 +8,38 @@
     <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>
               </listitem>
             </varlistentry>
 
+            <varlistentry>
+              <term><option>TAG</option></term>
+              <listitem>
+                <para>Match against a device tag.</para>
+              </listitem>
+            </varlistentry>
+
             <varlistentry>
               <term><option>TEST{<replaceable>octal mode mask</replaceable>}</option></term>
               <listitem>
             <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.</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>
 
             <varlistentry>
               <term><option>ENV{<replaceable>key</replaceable>}</option></term>
               <listitem>
-                <para>Set a device property value.</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 specified 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>
 
                     <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>
               </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>