linux/Documentation/filesystems
NeilBrown cf20d349ae seq_file: document how per-entry resources are managed.
commit b3656d8227 upstream.

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 1f4aace60b ("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.

[akpm@linux-foundation.org: fix typo, per Willy]

Link: https://lkml.kernel.org/r/161248518659.21478.2484341937387294998.stgit@noble1
Link: https://lkml.kernel.org/r/161248539020.21478.3147971477400875336.stgit@noble1
Fixes: 1f4aace60b ("fs/seq_file.c: simplify seq_file iteration code and interface")
Signed-off-by: NeilBrown <neilb@suse.de>
Cc: Xin Long <lucien.xin@gmail.com>
Cc: Alexander Viro <viro@zeniv.linux.org.uk>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: Dave Hansen <dave.hansen@linux.intel.com>
Cc: Andy Lutomirski <luto@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Vlad Yasevich <vyasevich@gmail.com>
Cc: Neil Horman <nhorman@tuxdriver.com>
Cc: Marcelo Ricardo Leitner <marcelo.leitner@gmail.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: <stable@vger.kernel.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2021-03-04 11:38:37 +01:00
..
caching
cifs
ext4
nfs
spufs
9p.rst
adfs.rst
affs.rst
afs.rst
api-summary.rst
autofs-mount-control.rst
autofs.rst
automount-support.rst
befs.rst
bfs.rst
btrfs.rst
ceph.rst
coda.rst
configfs.rst
cramfs.rst
dax.txt
debugfs.rst
devpts.rst
directory-locking.rst
dlmfs.rst
dnotify.rst
ecryptfs.rst
efivarfs.rst
erofs.rst
ext2.rst
ext3.rst
f2fs.rst
fiemap.rst
files.rst
fscrypt.rst
fsverity.rst
fuse-io.rst
fuse.rst
gfs2-glocks.rst
gfs2-uevents.rst
gfs2.rst
hfs.rst
hfsplus.rst
hpfs.rst
index.rst
inotify.rst
isofs.rst
journalling.rst
locking.rst
locks.rst
mandatory-locking.rst
mount_api.rst
nilfs2.rst
ntfs.rst
ocfs2-online-filecheck.rst
ocfs2.rst
omfs.rst
orangefs.rst
overlayfs.rst
path-lookup.rst
path-lookup.txt
porting.rst
proc.rst
qnx6.rst
quota.rst
ramfs-rootfs-initramfs.rst
relay.rst
romfs.rst
seq_file.rst
sharedsubtree.rst
splice.rst
squashfs.rst
sysfs.rst
sysv-fs.rst
tmpfs.rst
ubifs-authentication.rst
ubifs.rst
udf.rst
vfat.rst
vfs.rst
virtiofs.rst
xfs-delayed-logging-design.rst
xfs-self-describing-metadata.rst
zonefs.rst