[PATCH RESUBMIT 2/2] Documentation/filesystem/seq_file: document seq_open_init()

[Rob Jones <rob.jones@codethink.co.uk>]

Add documentation for new function and restructure existing text
in the same area.

Signed-off-by: Rob Jones <rob.jones@codethink.co.uk>
---
 Documentation/filesystems/seq_file.txt |   58 +++++++++++++++++++++-----------
 1 file changed, 39 insertions(+), 19 deletions(-)

diff --git a/Documentation/filesystems/seq_file.txt b/Documentation/filesystems/seq_file.txt
index 420fc0d..10a3be6 100644
--- a/Documentation/filesystems/seq_file.txt
+++ b/Documentation/filesystems/seq_file.txt
@@ -221,15 +221,37 @@ Here, the call to seq_open() takes the seq_operations structure we created
 before, and gets set up to iterate through the virtual file.
 
 On a successful open, seq_open() stores the struct seq_file pointer in
-file->private_data. If you have an application where the same iterator can
-be used for more than one file, you can store an arbitrary pointer in the
-private field of the seq_file structure; that value can then be retrieved
-by the iterator functions.
+file->private_data.
 
-There is also a wrapper function to seq_open() called seq_open_private(). It
-kmallocs a zero filled block of memory and stores a pointer to it in the
-private field of the seq_file structure, returning 0 on success. The
-block size is specified in a third parameter to the function, e.g.:
+Many applications can use the same iterator for more than one file. You can
+store an arbitrary pointer in the private field of the seq_file structure;
+that value can then be retrieved by the iterator functions.
+
+To facilitate this, a number of wrapper functions to seq_open() are
+provided:
+
++----------------------+---------------------------------------------------------+
+|      Function        | Use case                                                |
++----------------------+---------------------------------------------------------+
+| seq_open()           | Iterator needs no pre-initialised data                  |
+| seq_open_init()      | Iterator needs a pointer to data but no kmalloc needed  |
+| seq_open_private()   | Iterator needs data but kzalloc() suffices              |
+| __seq_open_private() | Iterator needs data with initialisation after kzalloc() |
++----------------------+---------------------------------------------------------+
+
+seq_open_init() is similiar to seq_open() except that it accepts a third
+parameter of type (void *) which it stores in the private field of the
+seq_file structure, e.g.:
+
+	static int ct_open(struct inode *inode, struct file *file)
+	{
+		return seq_open_init(file, &ct_seq_ops, &mystruct);
+	}
+
+seq_open_private() is similar to seq_open_init() except that the third
+parameter is a size. The function kmallocs a zero filled block of memory
+of the supplied size and stores a pointer to this block in the private
+field of the seq_file structure, returning 0 on success, e.g.:
 
 	static int ct_open(struct inode *inode, struct file *file)
 	{
@@ -237,15 +259,14 @@ block size is specified in a third parameter to the function, e.g.:
 					sizeof(struct mystruct));
 	}
 
-There is also a variant function, __seq_open_private(), which is functionally
-identical except that, if successful, it returns the pointer to the allocated
-memory block, allowing further initialisation e.g.:
+__seq_open_private()is a variant of seq_open_private(), functionally
+identical except that, if successful, it returns the pointer to the
+allocated memory block, allowing further initialisation, e.g.:
 
 	static int ct_open(struct inode *inode, struct file *file)
 	{
-		struct mystruct *p =
-			__seq_open_private(file, &ct_seq_ops, sizeof(*p));
-
+		struct mystruct *p;
+		p = __seq_open_private(file, &ct_seq_ops, sizeof(*p));
 		if (!p)
 			return -ENOMEM;
 
@@ -256,9 +277,6 @@ memory block, allowing further initialisation e.g.:
 		return 0;
 	}
 
-A corresponding close function, seq_release_private() is available which
-frees the memory allocated in the corresponding open.
-
 The other operations of interest - read(), llseek(), and release() - are
 all implemented by the seq_file code itself. So a virtual file's
 file_operations structure will look like:
@@ -271,8 +289,10 @@ file_operations structure will look like:
 	        .release = seq_release
 	};
 
-There is also a seq_release_private() which passes the contents of the
-seq_file private field to kfree() before releasing the structure.
+There is also wrapper function, seq_release_private(), which can be used
+instead of seq_release(). It is identical except that it passes the contents
+of the seq_file private field to kfree() before releasing the seq_file
+structure itself.
 
 The final step is the creation of the /proc file itself. In the example
 code, that is done in the initialization code in the usual way:
-- 
1.7.10.4