unprivileged btrfs subvol list

Documentation/Makefile.in

@@ -23,6 +23,7 @@ endif
 endif
 
 mandir ?= $(prefix)/share/man
+man2dir = $(mandir)/man2
 man3dir = $(mandir)/man3
 man5dir = $(mandir)/man5
 man8dir = $(mandir)/man8
@@ -44,8 +45,10 @@ help:
  @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 install: man
+ $(INSTALL) -d -m 755 $(DESTDIR)$(man2dir)
  $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
  $(INSTALL) -d -m 755 $(DESTDIR)$(man8dir)
+ $(INSTALL) -m 644 $(BUILDDIR)/man/*.2 $(DESTDIR)$(man2dir)
  $(INSTALL) -m 644 $(BUILDDIR)/man/*.5 $(DESTDIR)$(man5dir)
  $(INSTALL) -m 644 $(BUILDDIR)/man/*.8 $(DESTDIR)$(man8dir)
  $(INSTALL) -m 644 btrfsck.8 $(DESTDIR)$(man8dir)

Documentation/btrfs-man5.rst

@@ -455,6 +455,7 @@ SEE ALSO
 :manref:`chattr(1)`,
 :manref:`fstrim(8)`,
 :manref:`ioctl(2)`,
+:doc:`btrfs-ioctl`,
 :doc:`mkfs.btrfs`,
 :manref:`mount(8)`,
 :manref:`swapon(8)`

Documentation/btrfs-subvolume.rst

@@ -112,6 +112,15 @@ delete [options] [<subvolume> [<subvolume>...]], delete -i|--subvolid <subvolid>
  -i|--subvolid <subvolid>
  subvolume id to be removed instead of the <path> that should point to the
  filesystem with the subvolume
+
+ -R|--recursive
+ delete subvolumes beneath each subvolume recursively
+
+ This requires either `CAP_SYS_ADMIN` or the filesystem must be
+ mounted with `user_subvol_rm_allowed` mount option.
+ In the unprivileged case, subvolumes which cannot be accessed
+ are skipped. The deletion is not atomic.
+
  -v|--verbose
  (deprecated) alias for global *-v* option
 
@@ -134,20 +143,47 @@ list [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path
 
  where *ID* is subvolume's (root)id, *generation* is an internal counter which is
  updated every transaction, *parent_ID* is the same as the parent subvolume's id,
- and *path* is the relative path of the subvolume to the top level subvolume.
+ and *path* is the path of the subvolume. The exact meaning of *path*
+ depends on the **Path filtering** option used.
+
+ If -O or -A is given, "top level" is replaced by "parent".
+
  The subvolume's ID may be used by the subvolume set-default command,
  or at mount time via the *subvolid=* option.
 
  ``Options``
 
  Path filtering:
 
+ -O
+ Print <path> and all subvolumes below it, recursively. <path>
+ must be a subvolume. Paths are printed relative to <path>.
+
+ This may be used by unprivileged users, in which case this only
+ lists subvolumes that the user has access to.
+ -A
+ Print all subvolumes in the filesystem. Paths are printed
+ relative to the root of the filesystem.
+
+ You likely always want either -O or -A. The -o and -a options and the
+ default if no path filtering options are given have very confusing,
+ accidental behavior that is only kept for backwards compatibility.
+
  -o
- Print only subvolumes below specified <path>. Note that this is not a
- recursive command, and won't show nested subvolumes under <path>.
+ Print only the immediate children subvolumes of the subvolume
+ containing <path>. Paths are printed relative to the root of
+ the filesystem.
  -a
- print all the subvolumes in the filesystem and distinguish between
- absolute and relative path with respect to the given *path*.
+ Print all subvolumes in the filesystem other than the root
+ subvolume. Paths are printed relative to the root of the
+ filesystem, except that subvolumes that are not an immediate
+ child of the subvolume containing <path> are prefixed with
+ "<FS_TREE>/".
+
+ If none of these are given, print all subvolumes in the filesystem
+ other than the root subvolume. Paths below the subvolume containing
+ <path> are printed relative to that subvolume, and other paths are
+ printed relative to the root of the filesystem.
 
  Field selection:
 

Documentation/conf.py

@@ -66,6 +66,7 @@
  ('btrfs-qgroup', 'btrfs-qgroup', 'control the quota group of a btrfs filesystem', '', 8),
  ('btrfs-property', 'btrfs-property', 'get/set/list properties for given filesystem object', '', 8),
  ('btrfs-inspect-internal', 'btrfs-inspect-internal', 'query various internal information', '', 8),
+ ('btrfs-ioctl', 'btrfs-ioctl', 'documentation about btrfs ioctls', '', 2),
  ('btrfs-image', 'btrfs-image', 'create/restore an image of the filesystem', '', 8),
  ('btrfs-find-root', 'btrfs-find-root', 'filter to find btrfs root', '', 8),
  ('btrfs-filesystem', 'btrfs-filesystem', 'command group that primarily does work on the whole filesystems', '', 8),