Kernel/linux-stable
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git synced 2024-12-29 17:25:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc: seq_file: clarify role of *pos in ->next()

Browse Source 
There are behavioural requirements on the seq_file next() function in
terms of how it updates *pos at end-of-file, and these are now enforced
by a warning.

I was recently attempting to justify the reason this was needed, and
couldn't remember the details, and didn't find them in the
documentation.

So I re-read the code until I understood it again, and updated the
documentation to match.

I also enhanced the text about SEQ_START_TOKEN as it seemed potentially
misleading.

Cc: Vasily Averin <vvs@virtuozzo.com>
Signed-off-by: NeilBrown <neilb@suse.de>
Link: https://lore.kernel.org/r/87eemqiazh.fsf@notabene.neil.brown.name
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
NeilBrown 2020-09-25 17:14:42 +10:00 committed by Jonathan Corbet
parent e0bc9cf0a7
commit ce7a7eed77
1 changed files with 19 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
Documentation/filesystems/seq_file.rst
View File

@ -129,7 +129,9 @@ also a special value which can be returned by the start() function
called SEQ_START_TOKEN; it can be used if you wish to instruct your
show() function (described below) to print a header at the top of the
output. SEQ_START_TOKEN should only be used if the offset is zero,
however.
however. SEQ_START_TOKEN has no special meaning to the core seq_file
code. It is provided as a convenience for a start() funciton to
communicate with the next() and show() functions.
The next function to implement is called, amazingly, next(); its job is to
move the iterator forward to the next position in the sequence. The
@ -145,6 +147,22 @@ complete. Here's the example version::
return spos;
}
The next() function should set ``*pos`` to a value that start() can use
to find the new location in the sequence. When the iterator is being
stored in the private data area, rather than being reinitialized on each
start(), it might seem sufficient to simply set ``*pos`` to any non-zero
value (zero always tells start() to restart the sequence). This is not
sufficient due to historical problems.
Historically, many next() functions have *not* updated ``*pos`` at
end-of-file. If the value is then used by start() to initialise the
iterator, this can result in corner cases where the last entry in the
sequence is reported twice in the file. In order to discourage this bug
from being resurrected, the core seq_file code now produces a warning if
a next() function does not change the value of ``*pos``. Consequently a
next() function *must* change the value of ``*pos``, and of course must
set it to a non-zero value.
The stop() function closes a session; its job, of course, is to clean
up. If dynamic memory is allocated for the iterator, stop() is the
place to free it; if a lock was taken by start(), stop() must release