btrfs-progs: docs: cross references, ioctl updates
[ci skip] Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba
parent
478a295b00
commit
9aafb384cb
|
|
@ -14,11 +14,15 @@ Bootloaders
|
|||
|
||||
.. include:: ch-bootloaders.rst
|
||||
|
||||
.. _administration-limits:
|
||||
|
||||
Filesystem limits
|
||||
-----------------
|
||||
|
||||
.. include:: ch-fs-limits.rst
|
||||
|
||||
.. _administration-flexibility:
|
||||
|
||||
Flexibility
|
||||
-----------
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
-----------
|
||||
|
|
|
|||
Loading…
Reference in a new issue