Document SEQ_SKIP
authorJonathan Corbet <corbet@lwn.net>
Wed, 23 Apr 2008 16:34:52 +0000 (10:34 -0600)
committerJonathan Corbet <corbet@lwn.net>
Thu, 24 Apr 2008 21:57:32 +0000 (15:57 -0600)
2.6.26 adds a SEQ_SKIP return value for the seq_file show() function;
update the documentation to match.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation/filesystems/seq_file.txt

index 7fb8e6dc62bfb596032725264c3b911a0cca2b2b..0ab92c260894a14f8510053647dece4bd9d48e26 100644 (file)
@@ -122,8 +122,7 @@ stop() is the place to free it.
        }
 
 Finally, the show() function should format the object currently pointed to
-by the iterator for output. It should return zero, or an error code if
-something goes wrong. The example module's show() function is:
+by the iterator for output.  The example module's show() function is:
 
        static int ct_seq_show(struct seq_file *s, void *v)
        {
@@ -132,6 +131,12 @@ something goes wrong. The example module's show() function is:
                return 0;
        }
 
+If all is well, the show() function should return zero.  A negative error
+code in the usual manner indicates that something went wrong; it will be
+passed back to user space.  This function can also return SEQ_SKIP, which
+causes the current item to be skipped; if the show() function has already
+generated output before returning SEQ_SKIP, that output will be dropped.
+
 We will look at seq_printf() in a moment. But first, the definition of the
 seq_file iterator is finished by creating a seq_operations structure with
 the four functions we have just defined: