diff options
author | Dimitri John Ledkov <xnox@ubuntu.com> | 2017-10-18 13:15:59 +0100 |
---|---|---|
committer | Dimitri John Ledkov <xnox@ubuntu.com> | 2017-10-18 13:15:59 +0100 |
commit | 74d288e05c2d0cb97186f51049813b3e5b5bb0cd (patch) | |
tree | 4fc213398dc89e053d53ff7d42102942470e9cb5 /Documentation | |
parent | 569a646293cd782de7665b6158514f3b48d229d3 (diff) |
New upstream release.
Diffstat (limited to 'Documentation')
35 files changed, 220 insertions, 34 deletions
diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in index 539c6b55..bdc3dc3f 100644 --- a/Documentation/Makefile.in +++ b/Documentation/Makefile.in @@ -32,19 +32,19 @@ MAN8_TXT += btrfs-property.asciidoc # Category 5 manual page MAN5_TXT += btrfs-man5.asciidoc -MAN_TXT = $(MAN8_TXT) $(MAN5_TXT) +MAN3_TXT += btrfs-ioctl.asciidoc + +MAN_TXT = $(MAN3_TXT) $(MAN8_TXT) $(MAN5_TXT) MAN_XML = $(patsubst %.asciidoc,%.xml,$(MAN_TXT)) MAN_HTML = $(patsubst %.asciidoc,%.html,$(MAN_TXT)) - -DOC_MAN5 = $(patsubst %.asciidoc,%.5,$(MAN5_TXT)) +GZ_MAN3 = $(patsubst %.asciidoc,%.3.gz,$(MAN3_TXT)) GZ_MAN5 = $(patsubst %.asciidoc,%.5.gz,$(MAN5_TXT)) - -DOC_MAN8 = $(patsubst %.asciidoc,%.8,$(MAN8_TXT)) GZ_MAN8 = $(patsubst %.asciidoc,%.8.gz,$(MAN8_TXT)) mandir ?= $(prefix)/share/man -man8dir = $(mandir)/man8 +man3dir = $(mandir)/man3 man5dir = $(mandir)/man5 +man8dir = $(mandir)/man8 ASCIIDOC = @ASCIIDOC@ ASCIIDOC_EXTRA = @@ -72,7 +72,8 @@ endif endif all: man -man: man5 man8 +man: man3 man5 man8 +man3: $(GZ_MAN3) man5: $(GZ_MAN5) man8: $(GZ_MAN8) html: $(MAN_HTML) @@ -99,12 +100,19 @@ uninstall: clean: $(QUIET_RM)$(RM) -f *.xml *.xml+ *.5 *.5.gz *.8 *.8.gz *.html +%.3.gz : %.3 + $(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@ + %.5.gz : %.5 $(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@ %.8.gz : %.8 $(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@ +%.3 : %.xml + $(QUIET_XMLTO)$(RM) -f $@ && \ + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + %.5 : %.xml $(QUIET_XMLTO)$(RM) -f $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< diff --git a/Documentation/btrfs-balance.8.gz b/Documentation/btrfs-balance.8.gz Binary files differindex 23cc2625..1d553317 100644 --- a/Documentation/btrfs-balance.8.gz +++ b/Documentation/btrfs-balance.8.gz diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc index fba55140..cc81de91 100644 --- a/Documentation/btrfs-balance.asciidoc +++ b/Documentation/btrfs-balance.asciidoc @@ -45,29 +45,27 @@ COMPATIBILITY NOTE: The balance subcommand also exists under the *btrfs filesystem* namespace. This still works for backward compatibility but is deprecated and -should not be used anymore. +should not be used any more. NOTE: A short syntax *btrfs balance <path>* works due to backward compatibility -but is deprecated and should not be used anymore. Use *btrfs balance start* +but is deprecated and should not be used any more. Use *btrfs balance start* command instead. PERFORMANCE IMPLICATIONS ------------------------ -Balance operation is intense namely in the IO respect, but can be also CPU -intense. It affects other actions on the filesystem. There are typically lots -of data being copied from one location to another, and lots of metadata get -updated. +Balancing operations are very IO intensive and can also be quite CPU intensive, +impacting other ongoing filesystem operations. Typically large amounts of data +are copied from one location to another, with corresponding metadata updates. -Depending on the actual block group layout, it can be also seek-heavy. The -performance on rotational devices is noticeably worse than on SSDs or fast -arrays. +Depending upon the block group layout, it can also be seek heavy. Performance +on rotational devices is noticeably worse compared to SSDs or fast arrays. SUBCOMMAND ---------- *cancel* <path>:: -cancel running or paused balance, the command will block and wait until the -actually processed blockgroup is finished +cancels a running or paused balance, the command will block and wait until the +current blockgroup being processed completes *pause* <path>:: pause running balance operation, this will store the state of the balance diff --git a/Documentation/btrfs-check.8.gz b/Documentation/btrfs-check.8.gz Binary files differindex 05538321..9f5c4bca 100644 --- a/Documentation/btrfs-check.8.gz +++ b/Documentation/btrfs-check.8.gz diff --git a/Documentation/btrfs-check.asciidoc b/Documentation/btrfs-check.asciidoc index 28ed9dd7..fbf48847 100644 --- a/Documentation/btrfs-check.asciidoc +++ b/Documentation/btrfs-check.asciidoc @@ -3,7 +3,7 @@ btrfs-check(8) NAME ---- -btrfs-check - check or repair an unmounted btrfs filesystem +btrfs-check - check or repair a btrfs filesystem SYNOPSIS -------- @@ -13,7 +13,9 @@ DESCRIPTION ----------- The filesystem checker is used to verify structural integrity of a filesystem -and attempt to repair it if requested. The filesystem must be unmounted. +and attempt to repair it if requested. It is recommended to unmount the +filesystem prior to running the check, but it is possible to start checking a +mounted filesystem (see '--force'). By default, *btrfs check* will not modify the device but you can reaffirm that by the option '--readonly'. @@ -60,7 +62,7 @@ show extent state for the given subvolume -p|--progress:: indicate progress at various checking phases ---qgroup-report:: +-Q|--qgroup-report:: verify qgroup accounting and compare against filesystem accounting -r|--tree-root <bytenr>:: @@ -120,6 +122,12 @@ needs to re-read blocks when needed. This may increase run time. NOTE: 'lowmem' mode does not work with '--repair' yet, and is still considered experimental. +--force:: +allow to work on a mounted filesystem. Note that this should work fine on a +quiescent or read-only mounted filesystem but may crash if the device is +changed externally, eg. by the kernel module. Repair without mount checks is +not supported right now. + EXIT STATUS ----------- *btrfs check* returns a zero exit status if it succeeds. Non zero is diff --git a/Documentation/btrfs-convert.8.gz b/Documentation/btrfs-convert.8.gz Binary files differindex 2ee31c05..9758a080 100644 --- a/Documentation/btrfs-convert.8.gz +++ b/Documentation/btrfs-convert.8.gz diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc index cbc1c730..07ff608a 100644 --- a/Documentation/btrfs-convert.asciidoc +++ b/Documentation/btrfs-convert.asciidoc @@ -3,7 +3,7 @@ btrfs-convert(8) NAME ---- -btrfs-convert - convert from ext2/3/4 filesystem to btrfs in-place +btrfs-convert - convert from ext2/3/4 or reiserfs filesystem to btrfs in-place SYNOPSIS -------- @@ -11,13 +11,22 @@ SYNOPSIS DESCRIPTION ----------- -*btrfs-convert* is used to convert existing ext2/3/4 filesystem image to a -btrfs filesystem in-place. The original filesystem image is accessible -subvolume named 'ext2_saved' as file 'image'. +*btrfs-convert* is used to convert existing source filesystem image to a btrfs +filesystem in-place. The original filesystem image is accessible in subvolume +named like 'ext2_saved' as file 'image'. -WARNING: If you are going to perform rollback to ext2/3/4, you should not -execute *btrfs balance* command on the converted filesystem. This will change -the extent layout and make *btrfs-convert* unable to rollback. +Supported filesystems: + +* ext2, ext3, ext4 -- original feature, always built in + +* reiserfs -- since version 4.13, opptinally built, requires libreiserfscore 3.6.27 + +The list of supported source filesystem by a given binary is listed at the end +of help (option '--help'). + +WARNING: If you are going to perform rollback to the original filesystem, you +should not execute *btrfs balance* command on the converted filesystem. This +will change the extent layout and make *btrfs-convert* unable to rollback. The conversion utilizes free space of the original filesystem. The exact estimate of the required space cannot be foretold. The final btrfs metadata @@ -38,8 +47,8 @@ NOTE: The source filesystem should be clean, you are encouraged to run the **REMOVE THE ORIGINAL FILESYSTEM METADATA** -By removing the 'ext2_saved' subvolume, all metadata of the original filesystem -will be removed: +By removing the subvolume named like 'ext2_saved' or 'reiserfs_saved', all +metadata of the original filesystem will be removed: # btrfs subvolume delete /mnt/ext2_saved diff --git a/Documentation/btrfs-device.8.gz b/Documentation/btrfs-device.8.gz Binary files differindex f9a2bb44..a457c952 100644 --- a/Documentation/btrfs-device.8.gz +++ b/Documentation/btrfs-device.8.gz diff --git a/Documentation/btrfs-filesystem.8.gz b/Documentation/btrfs-filesystem.8.gz Binary files differindex 1dac3e56..b1628e4c 100644 --- a/Documentation/btrfs-filesystem.8.gz +++ b/Documentation/btrfs-filesystem.8.gz diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc index b60ef74b..41b30320 100644 --- a/Documentation/btrfs-filesystem.asciidoc +++ b/Documentation/btrfs-filesystem.asciidoc @@ -112,7 +112,7 @@ KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter). be verbose, print file names as they're submitted for defragmentation -c[<algo>]:::: compress file contents while defragmenting. Optional argument selects the compression -algorithm, 'zlib' (default) or 'lzo'. Currently it's not possible to select no +algorithm, 'zlib' (default), 'lzo' or 'zstd'. Currently it's not possible to select no compression. See also section 'EXAMPLES'. -r:::: defragment files recursively in given directories diff --git a/Documentation/btrfs-find-root.8.gz b/Documentation/btrfs-find-root.8.gz Binary files differindex beda326d..bbe8ad41 100644 --- a/Documentation/btrfs-find-root.8.gz +++ b/Documentation/btrfs-find-root.8.gz diff --git a/Documentation/btrfs-image.8.gz b/Documentation/btrfs-image.8.gz Binary files differindex 518b0714..cc7fc7ba 100644 --- a/Documentation/btrfs-image.8.gz +++ b/Documentation/btrfs-image.8.gz diff --git a/Documentation/btrfs-inspect-internal.8.gz b/Documentation/btrfs-inspect-internal.8.gz Binary files differindex 3072fda0..145bbb3d 100644 --- a/Documentation/btrfs-inspect-internal.8.gz +++ b/Documentation/btrfs-inspect-internal.8.gz diff --git a/Documentation/btrfs-ioctl.asciidoc b/Documentation/btrfs-ioctl.asciidoc new file mode 100644 index 00000000..11bf62b1 --- /dev/null +++ b/Documentation/btrfs-ioctl.asciidoc @@ -0,0 +1,140 @@ +btrfs-ioctl(3) +================ + +NAME +---- + +btrfs-ioctl - documentation for the ioctl interface to btrfs + +DATA STRUCTURES AND DEFINITIONS +------------------------------- + +[verse] +struct btrfs_ioctl_vol_args { + __s64 fd; + char name[BTRFS_PATH_NAME_MAX + 1]; +}; + +[verse] +struct btrfs_ioctl_vol_args_v2 { + \__s64 fd; + \__u64 transid; + \__u64 flags; + union { + struct { + \__u64 size; + struct btrfs_qgroup_inherit \__user *qgroup_inherit; + }; + __u64 unused[4]; + }; + char name[BTRFS_SUBVOL_NAME_MAX + 1]; +}; + +[verse] +BTRFS_SUBVOL_NAME_MAX = 4039 +BTRFS_PATH_NAME_MAX = 4087 + +LIST OF IOCTLS +-------------- + + BTRFS_IOC_SUBVOL_CREATE -- (obsolete) create a subvolume + BTRFS_IOC_SNAP_CREATE + BTRFS_IOC_DEFRAG + BTRFS_IOC_RESIZE + BTRFS_IOC_SCAN_DEV + BTRFS_IOC_TRANS_START + BTRFS_IOC_TRANS_END + BTRFS_IOC_SYNC + BTRFS_IOC_CLONE + BTRFS_IOC_ADD_DEV + BTRFS_IOC_RM_DEV + BTRFS_IOC_BALANCE + BTRFS_IOC_CLONE_RANGE + BTRFS_IOC_SUBVOL_CREATE + BTRFS_IOC_SNAP_DESTROY + BTRFS_IOC_DEFRAG_RANGE + BTRFS_IOC_TREE_SEARCH + BTRFS_IOC_TREE_SEARCH_V2 + BTRFS_IOC_INO_LOOKUP + BTRFS_IOC_DEFAULT_SUBVOL + BTRFS_IOC_SPACE_INFO + BTRFS_IOC_START_SYNC + BTRFS_IOC_WAIT_SYNC + BTRFS_IOC_SNAP_CREATE_V2 + BTRFS_IOC_SUBVOL_CREATE_V2 -- create a subvolume + BTRFS_IOC_SUBVOL_GETFLAGS + BTRFS_IOC_SUBVOL_SETFLAGS + BTRFS_IOC_SCRUB + BTRFS_IOC_SCRUB_CANCEL + BTRFS_IOC_SCRUB_PROGRESS + BTRFS_IOC_DEV_INFO + BTRFS_IOC_FS_INFO + BTRFS_IOC_BALANCE_V2 + BTRFS_IOC_BALANCE_CTL + BTRFS_IOC_BALANCE_PROGRESS + BTRFS_IOC_INO_PATHS + BTRFS_IOC_LOGICAL_INO + BTRFS_IOC_SET_RECEIVED_SUBVOL + BTRFS_IOC_SEND + BTRFS_IOC_DEVICES_READY + BTRFS_IOC_QUOTA_CTL + BTRFS_IOC_QGROUP_ASSIGN + BTRFS_IOC_QGROUP_CREATE + BTRFS_IOC_QGROUP_LIMIT + BTRFS_IOC_QUOTA_RESCAN + BTRFS_IOC_QUOTA_RESCAN_STATUS + BTRFS_IOC_QUOTA_RESCAN_WAIT + BTRFS_IOC_GET_FSLABEL + BTRFS_IOC_SET_FSLABEL + BTRFS_IOC_GET_DEV_STATS + BTRFS_IOC_DEV_REPLACE + BTRFS_IOC_FILE_EXTENT_SAME + BTRFS_IOC_GET_FEATURES + BTRFS_IOC_SET_FEATURES + BTRFS_IOC_GET_SUPPORTED_FEATURES + +DETAILED DESCRIPTION +-------------------- + +BTRFS_IOC_SUBVOL_CREATE +~~~~~~~~~~~~~~~~~~~~~~~ +NOTE: obsoleted by BTRFS_IOC_SUBVOL_CREATE_V2 + +_(since: 3.0, obsoleted: 4.0)_ Create a subvolume. + +ioctl fd:: file descriptor of the parent directory of the new subvolume +argument:: struct btrfs_ioctl_vol_args +fd:: ignored +name:: name of the subvolume, although the buffer can be almost 4k, the file +size is limited by linux VFS to 255 characters and must not contain a slash +('/') + + +BTRFS_IOC_SUBVOL_CREATE_V2 +~~~~~~~~~~~~~~~~~~~~~~~~~~ +NOTE: obsoletes BTRFS_IOC_SUBVOL_CREATE + +_(since: 3.6)_ Create a subvolume, qgroup inheritance can be specified. + +ioctl fd:: file descriptor of the parent directory of the new subvolume +argument:: struct btrfs_ioctl_vol_args_v2 +fd:: ignored +transid:: ignored +flags:: ignored +size:: ... +qgroup_inherit:: ... +name:: name of the subvolume, although the buffer can be almost 4k, the file +size is limited by linux VFS to 255 characters and must not contain a slash +('/') +devid:: ... + + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`ioctl`(2) diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc index 8d9031f5..3981435e 100644 --- a/Documentation/btrfs-man5.asciidoc +++ b/Documentation/btrfs-man5.asciidoc @@ -118,7 +118,7 @@ but a warning is printed if it's more than 300 seconds (5 minutes). (default: off) + Control BTRFS file data compression. Type may be specified as 'zlib', -'lzo' or 'no' (for no compression, used for remounting). If no type +'lzo', 'zstd' or 'no' (for no compression, used for remounting). If no type is specified, 'zlib' is used. If 'compress-force' is specified, the compression will allways be attempted, but the data may end up uncompressed if the compression would make them larger. @@ -472,6 +472,12 @@ page size the 'lzo' compression has been used on the filesystem, either as a mount option or via *btrfs filesystem defrag*. +*compress_zstd*:: +(since: 4.14) ++ +the 'zstd' compression has been used on the filesystem, either as a mount option +or via *btrfs filesystem defrag*. + *default_subvol*:: (since: 2.6.34) + diff --git a/Documentation/btrfs-map-logical.8.gz b/Documentation/btrfs-map-logical.8.gz Binary files differindex e8f26048..ce04a33a 100644 --- a/Documentation/btrfs-map-logical.8.gz +++ b/Documentation/btrfs-map-logical.8.gz diff --git a/Documentation/btrfs-property.8.gz b/Documentation/btrfs-property.8.gz Binary files differindex 34e80ae4..e8a46fc9 100644 --- a/Documentation/btrfs-property.8.gz +++ b/Documentation/btrfs-property.8.gz diff --git a/Documentation/btrfs-property.asciidoc b/Documentation/btrfs-property.asciidoc index 05ab0bc7..7ed6a7df 100644 --- a/Documentation/btrfs-property.asciidoc +++ b/Documentation/btrfs-property.asciidoc @@ -43,7 +43,7 @@ read-only flag of subvolume: true or false label:::: label of device compression:::: -compression setting for an inode: lzo, zlib, or "" (empty string) +compression setting for an inode: lzo, zlib, zstd, or "" (empty string) *list* [-t <type>] <object>:: Lists available properties with their descriptions for the given object. diff --git a/Documentation/btrfs-qgroup.8.gz b/Documentation/btrfs-qgroup.8.gz Binary files differindex d6b7b036..8201a6e9 100644 --- a/Documentation/btrfs-qgroup.8.gz +++ b/Documentation/btrfs-qgroup.8.gz diff --git a/Documentation/btrfs-quota.8.gz b/Documentation/btrfs-quota.8.gz Binary files differindex cef3cede..7c6c3001 100644 --- a/Documentation/btrfs-quota.8.gz +++ b/Documentation/btrfs-quota.8.gz diff --git a/Documentation/btrfs-quota.asciidoc b/Documentation/btrfs-quota.asciidoc index ef2e5d33..f882647d 100644 --- a/Documentation/btrfs-quota.asciidoc +++ b/Documentation/btrfs-quota.asciidoc @@ -96,7 +96,23 @@ instead of '0/ID'. For all higher levels, the ID can be chosen freely. Each qgroup can contain a set of lower level qgroups, thus creating a hierarchy of qgroups. Figure 1 shows an example qgroup tree. -// TODO: insert Figure 1 + +---+ + |2/1| + +---+ + / \ + +---+/ \+---+ + |1/1| |1/2| + +---+ +---+ + / \ / \ + +---+/ \+---+/ \+---+ +qgroups |0/1| |0/2| |0/3| + +-+-+ +---+ +---+ + | / \ / \ + | / \ / \ + | / \ / \ +extents 1 2 3 4 + +Figure1: Sample qgroup hierarchy At the bottom, some extents are depicted showing which qgroups reference which extents. It is important to understand the notion of 'referenced' vs diff --git a/Documentation/btrfs-receive.8.gz b/Documentation/btrfs-receive.8.gz Binary files differindex f06a31a0..4b53e360 100644 --- a/Documentation/btrfs-receive.8.gz +++ b/Documentation/btrfs-receive.8.gz diff --git a/Documentation/btrfs-replace.8.gz b/Documentation/btrfs-replace.8.gz Binary files differindex 9e69a725..75fce06e 100644 --- a/Documentation/btrfs-replace.8.gz +++ b/Documentation/btrfs-replace.8.gz diff --git a/Documentation/btrfs-rescue.8.gz b/Documentation/btrfs-rescue.8.gz Binary files differindex fba9170b..cbf07923 100644 --- a/Documentation/btrfs-rescue.8.gz +++ b/Documentation/btrfs-rescue.8.gz diff --git a/Documentation/btrfs-rescue.asciidoc b/Documentation/btrfs-rescue.asciidoc index a9b471fe..24b619c6 100644 --- a/Documentation/btrfs-rescue.asciidoc +++ b/Documentation/btrfs-rescue.asciidoc @@ -57,6 +57,7 @@ or less if the commit was implied by other filesystem activity. + One can determine whether *zero-log* is needed according to the kernel backtrace: ++ ---- ? replay_one_dir_item+0xb5/0xb5 [btrfs] ? walk_log_tree+0x9c/0x19d [btrfs] diff --git a/Documentation/btrfs-restore.8.gz b/Documentation/btrfs-restore.8.gz Binary files differindex 33da7fc7..2fa149f6 100644 --- a/Documentation/btrfs-restore.8.gz +++ b/Documentation/btrfs-restore.8.gz diff --git a/Documentation/btrfs-scrub.8.gz b/Documentation/btrfs-scrub.8.gz Binary files differindex 4ebd23dd..edfc4390 100644 --- a/Documentation/btrfs-scrub.8.gz +++ b/Documentation/btrfs-scrub.8.gz diff --git a/Documentation/btrfs-select-super.8.gz b/Documentation/btrfs-select-super.8.gz Binary files differindex 87f421d8..2cf064db 100644 --- a/Documentation/btrfs-select-super.8.gz +++ b/Documentation/btrfs-select-super.8.gz diff --git a/Documentation/btrfs-send.8.gz b/Documentation/btrfs-send.8.gz Binary files differindex 100458c8..06002bd1 100644 --- a/Documentation/btrfs-send.8.gz +++ b/Documentation/btrfs-send.8.gz diff --git a/Documentation/btrfs-subvolume.8.gz b/Documentation/btrfs-subvolume.8.gz Binary files differindex 262073ff..3d8519a5 100644 --- a/Documentation/btrfs-subvolume.8.gz +++ b/Documentation/btrfs-subvolume.8.gz diff --git a/Documentation/btrfs.5.gz b/Documentation/btrfs.5.gz Binary files differindex 9b97da35..b72078a8 100644 --- a/Documentation/btrfs.5.gz +++ b/Documentation/btrfs.5.gz diff --git a/Documentation/btrfs.8.gz b/Documentation/btrfs.8.gz Binary files differindex 4c151f07..0330e855 100644 --- a/Documentation/btrfs.8.gz +++ b/Documentation/btrfs.8.gz diff --git a/Documentation/btrfstune.8.gz b/Documentation/btrfstune.8.gz Binary files differindex 0d2d6445..30a81a82 100644 --- a/Documentation/btrfstune.8.gz +++ b/Documentation/btrfstune.8.gz diff --git a/Documentation/fsck.btrfs.8.gz b/Documentation/fsck.btrfs.8.gz Binary files differindex 77706f2f..86c8bfc6 100644 --- a/Documentation/fsck.btrfs.8.gz +++ b/Documentation/fsck.btrfs.8.gz diff --git a/Documentation/mkfs.btrfs.8.gz b/Documentation/mkfs.btrfs.8.gz Binary files differindex c6fc318d..11956269 100644 --- a/Documentation/mkfs.btrfs.8.gz +++ b/Documentation/mkfs.btrfs.8.gz |