Documentation: seq_file: Document seq_open_private(), seq_release_private()

Despite the fact that these functions have been around for years, they are little used (only 15 uses in 13 files at the preseht time) even though many other files use work-arounds to achieve the same result. By documenting them, hopefully they will become more widely used. Signed-off-by: Rob Jones <rob.jones@codethink.co.uk> Acked-by: Steven Whitehouse <swhiteho@redhat.com> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

Documentation: seq_file: Document seq_open_private(), seq_release_private()
Despite the fact that these functions have been around for years, they are little used (only 15 uses in 13 files at the preseht time) even though many other files use work-arounds to achieve the same result. By documenting them, hopefully they will become more widely used. Signed-off-by: Rob Jones <rob.jones@codethink.co.uk> Acked-by: Steven Whitehouse <swhiteho@redhat.com> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Rob Jones · Linus Torvalds
1 parent 6fef37c9a7
Showing 1 changed file with 33 additions and 0 deletions Side-by-side Diff
Documentation/filesystems/seq_file.txt
@@ -235,6 +235,39 @@
 private field of the seq_file structure; that value can then be retrieved
 by the iterator functions.
  
+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.:
+
+	static int ct_open(struct inode *inode, struct file *file)
+	{
+		return seq_open_private(file, &ct_seq_ops,
+					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.:
+
+	static int ct_open(struct inode *inode, struct file *file)
+	{
+		struct mystruct *p =
+			__seq_open_private(file, &ct_seq_ops, sizeof(*p));
+
+		if (!p)
+			return -ENOMEM;
+
+		p->foo = bar; /* initialize my stuff */
+			...
+		p->baz = true;
+
+		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:
...	...	@@ -235,6 +235,39 @@
235	235	private field of the seq_file structure; that value can then be retrieved
236	236	by the iterator functions.
237	237
	238	+There is also a wrapper function to seq_open() called seq_open_private(). It
	239	+kmallocs a zero filled block of memory and stores a pointer to it in the
	240	+private field of the seq_file structure, returning 0 on success. The
	241	+block size is specified in a third parameter to the function, e.g.:
	242	+
	243	+ static int ct_open(struct inode inode, struct file file)
	244	+ {
	245	+ return seq_open_private(file, &ct_seq_ops,
	246	+ sizeof(struct mystruct));
	247	+ }
	248	+
	249	+There is also a variant function, __seq_open_private(), which is functionally
	250	+identical except that, if successful, it returns the pointer to the allocated
	251	+memory block, allowing further initialisation e.g.:
	252	+
	253	+ static int ct_open(struct inode inode, struct file file)
	254	+ {
	255	+ struct mystruct *p =
	256	+ __seq_open_private(file, &ct_seq_ops, sizeof(*p));
	257	+
	258	+ if (!p)
	259	+ return -ENOMEM;
	260	+
	261	+ p->foo = bar; /* initialize my stuff */
	262	+ ...
	263	+ p->baz = true;
	264	+
	265	+ return 0;
	266	+ }
	267	+
	268	+A corresponding close function, seq_release_private() is available which
	269	+frees the memory allocated in the corresponding open.
	270	+
238	271	The other operations of interest - read(), llseek(), and release() - are
239	272	all implemented by the seq_file code itself. So a virtual file's
240	273	file_operations structure will look like: