path: root/Documentation/filesystems
diff options
authorNeilBrown <>2021-02-25 17:22:25 -0800
committerLinus Torvalds <>2021-02-26 09:41:05 -0800
commitb3656d8227f4c45812c6b40815d8f4e446ed372a (patch)
treec3b2726e6af82b6b14da81bcfaf5ca58efad84f0 /Documentation/filesystems
parent3159ed57792be7453793bda27297a423e1c63d6c (diff)
seq_file: document how per-entry resources are managed.
Patch series "Fix some seq_file users that were recently broken". A recent change to seq_file broke some users which were using seq_file in a non-"standard" way ... though the "standard" isn't documented, so they can be excused. The result is a possible leak - of memory in one case, of references to a 'transport' in the other. These three patches: 1/ document and explain the problem 2/ fix the problem user in x86 3/ fix the problem user in net/sctp This patch (of 3): Users of seq_file will sometimes find it convenient to take a resource, such as a lock or memory allocation, in the ->start or ->next operations. These are per-entry resources, distinct from per-session resources which are taken in ->start and released in ->stop. The preferred management of these is release the resource on the subsequent call to ->next or ->stop. However prior to Commit 1f4aace60b0e ("fs/seq_file.c: simplify seq_file iteration code and interface") it happened that ->show would always be called after ->start or ->next, and a few users chose to release the resource in ->show. This is no longer reliable. Since the mentioned commit, ->next will always come after a successful ->show (to ensure m->index is updated correctly), so the original ordering cannot be maintained. This patch updates the documentation to clearly state the required behaviour. Other patches will fix the few problematic users. [ fix typo, per Willy] Link: Link: Fixes: 1f4aace60b0e ("fs/seq_file.c: simplify seq_file iteration code and interface") Signed-off-by: NeilBrown <> Cc: Xin Long <> Cc: Alexander Viro <> Cc: Jonathan Corbet <> Cc: Ingo Molnar <> Cc: Dave Hansen <> Cc: Andy Lutomirski <> Cc: Peter Zijlstra <> Cc: Vlad Yasevich <> Cc: Neil Horman <> Cc: Marcelo Ricardo Leitner <> Cc: "David S. Miller" <> Cc: <> Signed-off-by: Andrew Morton <> Signed-off-by: Linus Torvalds <>
Diffstat (limited to 'Documentation/filesystems')
1 files changed, 6 insertions, 0 deletions
diff --git a/Documentation/filesystems/seq_file.rst b/Documentation/filesystems/seq_file.rst
index 56856481dc8d..a6726082a7c2 100644
--- a/Documentation/filesystems/seq_file.rst
+++ b/Documentation/filesystems/seq_file.rst
@@ -217,6 +217,12 @@ between the calls to start() and stop(), so holding a lock during that time
is a reasonable thing to do. The seq_file code will also avoid taking any
other locks while the iterator is active.
+The iterater value returned by start() or next() is guaranteed to be
+passed to a subsequent next() or stop() call. This allows resources
+such as locks that were taken to be reliably released. There is *no*
+guarantee that the iterator will be passed to show(), though in practice
+it often will be.
Formatted output