remove debug output during rules parsing

[elogind.git] / udev / udev.xml

diff --git a/udev/udev.xml b/udev/udev.xml
index 4c35e197911ee16b7b30e10d3ba8f99f537a4494..d2277c93d0d60e3b4b84ba3138237968ff9f5826 100644 (file)
--- a/udev/udev.xml
+++ b/udev/udev.xml
@@ -8,14 +8,12 @@
     <refentry>
       <refentryinfo>
         <title>udev</title>
     <refentry>
       <refentryinfo>
         <title>udev</title>

-        <date>August 2005</date>

         <productname>udev</productname>
       </refentryinfo>
 
       <refmeta>
         <refentrytitle>udev</refentrytitle>
         <manvolnum>7</manvolnum>
         <productname>udev</productname>
       </refentryinfo>
 
       <refmeta>
         <refentrytitle>udev</refentrytitle>
         <manvolnum>7</manvolnum>

-        <refmiscinfo class="version"></refmiscinfo>

       </refmeta>
 
       <refnamediv>
       </refmeta>
 
       <refnamediv>


@@ -90,7 +88,7 @@
           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>
 
           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 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>
           a comma. Each key has a distinct operation, depending on the used operator. Valid
           operators are:</para>
           <variablelist>


@@ -104,7 +102,7 @@
             <varlistentry>
               <term><option>!=</option></term>
               <listitem>
             <varlistentry>
               <term><option>!=</option></term>
               <listitem>

-                <para>Compare for non-equality.</para>
+                <para>Compare for inequality.</para>

               </listitem>
             </varlistentry>
 
               </listitem>
             </varlistentry>
 


@@ -168,6 +166,16 @@
               </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>SUBSYSTEM</option></term>
               <listitem>


@@ -229,6 +237,13 @@
               </listitem>
             </varlistentry>
 
               </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>TEST{<replaceable>octal mode mask</replaceable>}</option></term>
               <listitem>


@@ -289,18 +304,30 @@
             <varlistentry>
               <term><option>NAME</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 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 receives
+                any event. Changing the node name from the kernel's default may result
+                in unexpected behavior and is not supported. Udev is only expected to
+                handle device node permissions and to create additional symlinks, which
+                do not conflict with the kernel device node names.</para>

               </listitem>
             </varlistentry>
 
             <varlistentry>
               <term><option>SYMLINK</option></term>
               <listitem>
               </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.
+                <para>The name of a symlink targeting the node. Every matching rule will 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
                 Multiple symlinks may be specified by separating the names by the space

-                character.</para>
+                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 of them will own the link, is undefined. Claiming
+                the same name for a node and links may result in unexpected behavior and is
+                not supported.
+                </para>

               </listitem>
             </varlistentry>
 
               </listitem>
             </varlistentry>
 


@@ -323,7 +350,21 @@
             <varlistentry>
               <term><option>ENV{<replaceable>key</replaceable>}</option></term>
               <listitem>
             <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>
 
               </listitem>
             </varlistentry>
 


@@ -334,13 +375,22 @@
                 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
                 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>
+                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 path is given, the program must be in 
+                <filename>/lib/udev</filename>, otherwise the full path must be
+                specified.</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>
                 <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>

+                <para>Program name and arguments are separated with spaces. To
+                include spaces in an argument, use single quotes. Please note
+                that this does not run through a shell.</para>

               </listitem>
             </varlistentry>
 
               </listitem>
             </varlistentry>
 


@@ -368,7 +418,9 @@
                     <term><option>program</option></term>
                     <listitem>
                       <para>Execute an external program specified as the assigned value and
                     <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>
                     </listitem>
                   </varlistentry>
                   <varlistentry>


@@ -378,6 +430,14 @@
                       environment key format.</para>
                     </listitem>
                   </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>parent</option></term>
                     <listitem>


@@ -398,7 +458,8 @@
             <varlistentry>
               <term><option>WAIT_FOR</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>
             </varlistentry>
 


@@ -407,26 +468,6 @@
               <listitem>
                 <para>Rule and device options:</para>
                 <variablelist>
               <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>
                   <varlistentry>
                     <term><option>link_priority=<replaceable>value</replaceable></option></term>
                     <listitem>


@@ -434,14 +475,6 @@
                       priorities overwrite existing symlinks of other devices. The default is 0.</para>
                     </listitem>
                   </varlistentry>
                       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>
                   <varlistentry>
                     <term><option>event_timeout=</option></term>
                     <listitem>


@@ -457,6 +490,13 @@
                       with this option.</para>
                     </listitem>
                   </varlistentry>
                       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>
                 </variablelist>
               </listitem>
             </varlistentry>


@@ -613,9 +653,6 @@
               </listitem>
             </varlistentry>
           </variablelist>
               </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>
 
         </refsect2>
       </refsect1>