btrfs-progs: docs: cross references, ioctl updates

[ci skip]

Signed-off-by: David Sterba <dsterba@suse.com>

Documentation/Administration.rst

@@ -14,11 +14,15 @@ Bootloaders
 
 .. include:: ch-bootloaders.rst
 
+.. _administration-limits:
+
 Filesystem limits
 -----------------
 
 .. include:: ch-fs-limits.rst
 
+.. _administration-flexibility:
+
 Flexibility
 -----------
 

Documentation/Common-features.rst

@@ -29,7 +29,8 @@ FIEMAP
 
 filesystem label
         another filesystem identification, could be used for mount or for better
-        recognition, can be set or read by an ioctl or by command :command:`btrfs filesystem label`
+        recognition, can be set or read by an ioctl or by command
+        :ref:`btrfs filesystem label<man-filesystem-label>`
 
 O_TMPFILE
         mode of open() syscall that creates a file with no associated directory
@@ -40,7 +41,7 @@ O_TMPFILE
 xattr, acl
         extended attributes (xattr) is a list of *key=value* pairs associated
         with a file, usually storing additional metadata related to security,
-        access control list in particular (ACL) or properties (:command:`btrfs property`)
+        access control list in particular (ACL) or properties (:doc:`btrfs-property`)
 
 cross-rename
         mode of *renameat2* syscall that can atomically swap 2 directory

Documentation/Introduction.rst

@@ -12,38 +12,36 @@ and easy administration. Its main features and benefits are:
 Feature overview:
 
 *  Extent based file storage
-*  2\ :sup:`64` byte == 16 EiB maximum file size (practical limit is 8 EiB due to Linux VFS)
-*  Space-efficient packing of small files
+*  2\ :sup:`64` byte == 16 EiB :ref:`maximum file size<administration-limits>` (practical limit is 8 EiB due to Linux VFS)
+*  :doc:`Space-efficient packing of small files<Inline-files>`
 *  Space-efficient indexed directories
-*  Dynamic inode allocation
-*  Writable snapshots, read-only snapshots
-*  Subvolumes (separate internal filesystem roots)
-*  Checksums on data and metadata (crc32c, xxhash, sha256, blake2b)
-*  Compression (ZLIB, LZO, ZSTD), heuristics
-*  Integrated multiple device support
+*  :ref:`Dynamic inode allocation<administration-flexibility>`
+*  :doc:`Writable snapshots, read-only snapshots, subvolumes (separate internal filesystem roots)<Subvolumes>`
+*  :doc:`Checksums on data and metadata<Checksumming>` (crc32c, xxhash, sha256, blake2b)
+*  :doc:`Compression (ZLIB, LZO, ZSTD), heuristics<Compression>`
+*  :doc:`Integrated multiple device support<Volume-management>`:
 
-    *  File Striping
-    *  File Mirroring
-    *  File Striping+Mirroring
-    *  Single and Dual Parity implementations (experimental, not production-ready)
-*  SSD (flash storage) awareness (TRIM/Discard for reporting free blocks for
-   reuse) and optimizations (e.g. avoiding unnecessary seek optimizations,
-   sending writes in clusters, even if they are from unrelated files. This
-   results in larger write operations and faster write throughput)
-*  Efficient incremental backup
-*  Background scrub process for finding and repairing errors of files with redundant copies
-*  Online filesystem defragmentation
-*  Offline filesystem check
-*  In-place conversion of existing ext2/3/4 and reiserfs file systems
-*  Seed devices. Create a (readonly) filesystem that acts as a template to seed
-   other Btrfs filesystems. The original filesystem and devices are included as
-   a readonly starting point for the new filesystem. Using copy on write, all
-   modifications are stored on different devices; the original is unchanged.
-*  Subvolume-aware quota support
-*  Send/receive of subvolume changes
+    * File Striping (like RAID0)
+    * File Mirroring (like RAID1 up to 4 copies)
+    * File Striping+Mirroring (like RAID10)
+    * Single and Dual Parity implementations (like RAID5/6, experimental, not production-ready)
 
-    *  Efficient incremental filesystem mirroring
-*  Batch, or out-of-band deduplication (happens after writes, not during)
-*  Swapfile support
-*  Tree-checker, post-read and pre-write metadata verification
-*  Zoned mode support (SMR/ZBC/ZNS friendly allocation)
+*  SSD/NVMe (flash storage) awareness, :doc:`TRIM/Discard<Trim>` for reporting free blocks for
+   reuse and optimizations (e.g. avoiding unnecessary seek optimizations,
+   sending writes in clusters.
+*  :doc:`Background scrub<Scrub>` process for finding and repairing errors of files with redundant copies
+*  :doc:`Online filesystem defragmentation<Defragmentation>`
+*  :doc:`Offline filesystem check<btrfs-check>`
+*  :doc:`In-place conversion<Convert>` of existing ext2/3/4 and reiserfs filesystems
+*  :doc:`Seeding device.<Seeding-device>` Create a (readonly) filesystem that
+   acts as a template to seed other Btrfs filesystems. The original filesystem
+   and devices are included as a readonly starting point for the new filesystem.
+   Using copy on write, all modifications are stored on different devices; the
+   original is unchanged.
+*  :doc:`Subvolume-aware quota<Qgroups>` support
+*  :doc:`Send/receive of subvolume changes<Send-receive>`, efficient
+   incremental filesystem mirroring and backup
+*  :doc:`Batch, or out-of-band deduplication<Deduplication>` (happens after writes, not during)
+*  :doc:`Swapfile support<Swapfile>`
+*  :doc:`Tree-checker<Tree-checker>`, post-read and pre-write metadata verification
+*  :doc:`Zoned mode support<Zoned-mode>` (SMR/ZBC/ZNS friendly allocation, emulated on non-zoned devices)

Documentation/btrfs-filesystem.rst

@@ -184,6 +184,8 @@ du [options] <path> [<path>..]
         --tbytes
                 show sizes in TiB, or TB with --si.
 
+.. _man-filesystem-label:
+
 label [<device>|<mountpoint>] [<newlabel>]
         Show or update the label of a filesystem. This works on a mounted filesystem or
         a filesystem image.

Documentation/btrfs-ioctl.rst

@@ -177,6 +177,18 @@ DATA STRUCTURES AND DEFINITIONS
                 __u8 reserved[944];			/* pad to 1k */
         };
 
+.. _struct_btrfs_ioctl_ino_lookup_args:
+
+.. code-block:: c
+
+        #define BTRFS_INO_LOOKUP_PATH_MAX               4080
+
+        struct btrfs_ioctl_ino_lookup_args {
+                __u64 treeid;
+                __u64 objectid;
+                char name[BTRFS_INO_LOOKUP_PATH_MAX];
+        };
+
 .. _constants-table:
 
 .. list-table::
@@ -196,6 +208,8 @@ DATA STRUCTURES AND DEFINITIONS
      - 255
    * - BTRFS_LABEL_SIZE
      - 256
+   * - BTRFS_FIRST_FREE_OBJECTID
+     - 256
 
 OVERVIEW
 --------
@@ -230,11 +244,15 @@ library dependency. Backward compatibility is guaranteed and incompatible
 changes usually lead to a new version of the ioctl. Enhancements of existing
 ioctls can happen and depend on additional flags to be set. Zeroed unused
 space is commonly understood as a mechanism to communicate the compatibility
-between kernel and userspace and thus zeroing is really important. In exceptional
+between kernel and userspace and thus *zeroing is really important*. In exceptional
 cases this is not enough and further flags need to be passed to distinguish
 between zero as implicit unused initialization and a valid zero value. Such
 cases are documented.
 
+File descriptors of regular files are obtained by ``int fd = open()``, directories
+opened as ``DIR *dir = opendir()`` can be converted to the corresponding
+file descriptor by ``fd = dirfd(dir)``.
+
 LIST OF IOCTLS
 --------------
 
@@ -289,9 +307,9 @@ LIST OF IOCTLS
    * - BTRFS_IOC_TREE_SEARCH_V2
      -
      -
-   * - BTRFS_IOC_INO_LOOKUP
-     -
-     -
+   * - :ref:`BTRFS_IOC_INO_LOOKUP<BTRFS_IOC_INO_LOOKUP>`
+     - resolve inode number to path, or lookup containing subvolume id
+     - :ref:`struct btrfs_ioctl_ino_lookup_args<struct_btrfs_ioctl_ino_lookup_args>`
    * - :ref:`BTRFS_IOC_DEFAULT_SUBVOL<BTRFS_IOC_DEFAULT_SUBVOL>`
      - set the default subvolume id
      - uint64_t
@@ -378,10 +396,10 @@ LIST OF IOCTLS
      -
    * - :ref:`BTRFS_IOC_GET_FSLABEL<BTRFS_IOC_GET_FSLABEL>`
      - read filesystem label
-     - char buffer[BTRFS_LABEL_SIZE]
+     - char buffer[:ref:`BTRFS_LABEL_SIZE<constants-table>`]
    * - :ref:`BTRFS_IOC_SET_FSLABEL<BTRFS_IOC_SET_FSLABEL>`
      - set the filesystem label
-     - char buffer[BTRFS_LABEL_SIZE]
+     - char buffer[:ref:`BTRFS_LABEL_SIZE<constants-table>`]
    * - BTRFS_IOC_GET_DEV_STATS
      -
      -
@@ -599,6 +617,50 @@ BTRFS_IOC_SNAP_DESTROY
        size is limited by Linux VFS to 255 characters and must not contain a slash
        ('/')
 
+.. _BTRFS_IOC_INO_LOOKUP:
+
+BTRFS_IOC_INO_LOOKUP
+~~~~~~~~~~~~~~~~~~~~
+
+Resolve inode number to a path (requires CAP_SYS_ADMIN), or read a containing
+subvolume id of the given file (unrestricted, special case).  The size of the
+path name buffer is shorter than *PATH_MAX* (4096), it's possible that the path
+is trimmed due to that. Also implemented by
+:ref:`btrfs inspect-internal rootid<man-inspect-rootid>`.
+
+The general case needs CAP_SYS_ADMIN and can resolve any file to its path.
+The special case for reading the containing subvolume is not restricted:
+
+.. code-block:: c
+
+        struct btrfs_ioctl_ino_lookup_args args;
+
+        fd = open("file", ...);
+        args.treeid = 0;
+        args.objectid = BTRFS_FIRST_FREE_OBJECTID;
+        ioctl(fd, BTRFS_IOC_INO_LOOKUP, &args);
+        /* args.treeid now contains the subvolume id */
+
+
+.. list-table::
+   :header-rows: 1
+
+   * - Field
+     - Description
+   * - ioctl fd
+     - file descriptor of the file or directory to lookup the subvolumeid
+   * - ioctl args
+     - :ref:`struct btrfs_ioctl_ino_lookup_args<struct_btrfs_ioctl_ino_lookup_args>`
+   * - args.treeid
+     - subvolume id against which the path should be resolved (needs
+       CAP_SYS_ADMIN), or 0 so the subvolume containing *fd* will be used
+   * - args.objectid
+     - inode number to lookup, *INODE_REF_KEY* with that key.objectid, or
+       :ref:`BTRFS_FIRST_FREE_OBJECTID<constants-table>` as special case to
+       read only the tree id and clear the *args.name* buffer
+   * - args.name
+     - path relative to the toplevel subvolume, or empty string
+
 .. _BTRFS_IOC_DEFAULT_SUBVOL:
 
 BTRFS_IOC_DEFAULT_SUBVOL

Documentation/btrfs-property.rst

@@ -73,6 +73,8 @@ get [-t <type>] <object> [<name>]
 list [-t <type>] <object>
         List available properties with their descriptions for the given object.
 
+.. _man-property-set:
+
 set [-f] [-t <type>] <object> <name> <value>
         Set *value* of property *name* on a given btrfs object.
 

Documentation/ch-subvolume-intro.rst

@@ -65,12 +65,13 @@ the subvolume on the filesystem that produced the stream. The use case relies
 on matching data on both sides. Changing the subvolume to read-write after it
 has been received requires to reset the *received_uuid*. As this is a notable
 change and could potentially break the incremental send use case, performing
-it by :command:`btrfs property set` requires force if that is really desired by user.
+it by :ref:`btrfs property set<man-property-set>` requires force if that is
+really desired by user.
 
 .. note::
    The safety checks have been implemented in 5.14.2, any subvolumes previously
    received (with a valid *received_uuid*) and read-write status may exist and
-   could still lead to problems with send/receive. You can use :command:`btrfs subvolume show`
+   could still lead to problems with send/receive. You can use :ref:`btrfs subvolume show<man-subvolume-show>`
    to identify them. Flipping the flags to read-only and back to
    read-write will reset the *received_uuid* manually.  There may exist a
    convenience tool in the future.
@@ -153,6 +154,8 @@ directories in the target snapshot preserve their original inode numbers.
 .. note::
    Inode number is not a filesystem-wide unique identifier, some applications
    assume that. Please use pair *subvolumeid:inodenumber* for that purpose.
+   The subvolume id can be read by :ref:`btrfs inspect-internal rootid<man-inspect-rootid>`
+   or by the ioctl :ref:`BTRFS_IOC_INO_LOOKUP`.
 
 Performance
 -----------