linux-toradex.git/Documentation/filesystems/seq_file.txt, branch v5.4

fs/seq_file.c: simplify seq_file iteration code and interface

2018-08-17T23:20:28+00:00

The documentation for seq_file suggests that it is necessary to be able
to move the iterator to a given offset, however that is not the case.
If the iterator is stored in the private data and is stable from one
read() syscall to the next, it is only necessary to support first/next
interactions.  Implementing this in a client is a little clumsy.

 - if ->start() is given a pos of zero, it should go to start of
   sequence.

 - if ->start() is given the name pos that was given to the most recent
   next() or start(), it should restore the iterator to state just
   before that last call

 - if ->start is given another number, it should set the iterator one
   beyond the start just before the last ->start or ->next call.

Also, the documentation says that the implementation can interpret the
pos however it likes (other than zero meaning start), but seq_file
increments the pos sometimes which does impose on the implementation.

This patch simplifies the interface for first/next iteration and
simplifies the code, while maintaining complete backward compatability.
Now:

 - if ->start() is given a pos of zero, it should return an iterator
   placed at the start of the sequence

 - if ->start() is given a non-zero pos, it should return the iterator
   in the same state it was after the last ->start or ->next.

This is particularly useful for interators which walk the multiple
chains in a hash table, e.g.  using rhashtable_walk*.  See
fs/gfs2/glock.c and drivers/staging/lustre/lustre/llite/vvp_dev.c

A large part of achieving this is to *always* call ->next after ->show
has successfully stored all of an entry in the buffer.  Never just
increment the index instead.  Also:

 - always pass &m->index to ->start() and ->next(), never a temp
   variable

 - don't clear ->from when ->count is zero, as ->from is dead when
   ->count is zero.

Some ->next functions do not increment *pos when they return NULL.  To
maintain compatability with this, we still need to increment m->index in
one place, if ->next didn't increment it.  Note that such ->next
functions are buggy and should be fixed.  A simple demonstration is

   dd if=/proc/swaps bs=1000 skip=1

Choose any block size larger than the size of /proc/swaps.  This will
always show the whole last line of /proc/swaps.

This patch doesn't work around buggy next() functions for this case.

[neilb@suse.com: ensure ->from is valid]
  Link: http://lkml.kernel.org/r/87601ryb8a.fsf@notabene.neil.brown.name
Signed-off-by: NeilBrown 
Acked-by: Jonathan Corbet 	[docs]
Tested-by: Jann Horn 
Cc: Alexander Viro 
Cc: Kees Cook 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds

Documentation: update seq_file

2014-12-29T22:40:18+00:00

Update descriptions of seq_path() and seq_path_root():
starting with commit v3.2-rc4-1-g02125a8, seq_path_root() no longer
changes the value of root;
starting with commit v3.2-rc7-104-g8c9379e, some arguments of seq_path()
and seq_path_root() are const.

Signed-off-by: Dmitry V. Levin 
Acked-by: Rob Landley 
Signed-off-by: Jonathan Corbet

seq_file: Rename seq_overflow() to seq_has_overflowed() and make public

2014-10-30T00:26:06+00:00

The return values of seq_printf/puts/putc are frequently misused.

Start down a path to remove all the return value uses of these
functions.

Move the seq_overflow() to a global inlined function called
seq_has_overflowed() that can be used by the users of seq_file() calls.

Update the documentation to not show return types for seq_printf
et al.  Add a description of seq_has_overflowed().

Link: http://lkml.kernel.org/p/848ac7e3d1c31cddf638a8526fa3c59fa6fdeb8a.1412031505.git.joe@perches.com

Cc: Al Viro 
Signed-off-by: Joe Perches 
[ Reworked the original patch from Joe ]
Signed-off-by: Steven Rostedt

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

2014-09-07T22:21:13+00:00

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 
Acked-by: Steven Whitehouse 
Signed-off-by: Randy Dunlap 
Signed-off-by: Linus Torvalds

Documentation/filesystems/seq_file.txt: create_proc_entry deprecated

2014-06-06T23:08:11+00:00

Linked article in seq_file.txt still uses create_proc_entry which was
removed in commit 80e928f7ebb9 ("proc: Kill create_proc_entry()").

This patch adds information for kernel 3.10 and above

Signed-off-by: Fabian Frederick 
Cc: Jonathan Corbet 
Cc: Randy Dunlap 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds

seq_file: use proc_create() in documentation

2009-12-16T15:20:07+00:00

Using create_proc_entry() + ->proc_fops assignment is racy because
->proc_fops will be NULL for some time, use proc_create() to avoid race.

Signed-off-by: Alexey Dobriyan 
Cc: Randy Dunlap 
Cc: Jonathan Corbet 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds

Doc: seq_file.txt fix wrong dd command example.

2009-09-10T20:33:35+00:00

Small error in the "dd" command example, "out=" should be "of=".

Signed-off-by: Jesper Dangaard Brouer 
Signed-off-by: Jonathan Corbet

Document seq_path_root()

2008-04-25T17:56:37+00:00

Signed-off-by: Jonathan Corbet

Document SEQ_SKIP

2008-04-24T21:57:32+00:00

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

Fix typos in Documentation/filesystems/seq_file.txt

2008-04-16T02:35:40+00:00

A couple of typos crept into the newly added document about the seq_file
interface.  This patch corrects those typos and simultaneously deletes
unnecessary trailing spaces.

Signed-off-by: Dmitri Vorobiev 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds