* [PATCH 2/7] mkfs: move mkfs.xfs.8 to an .in file
2018-06-12 19:31 [PATCH 0/7] mkfs config support cleanups Eric Sandeen
2018-06-12 19:31 ` [PATCH 1/7] mkfs: document the config file option Eric Sandeen
@ 2018-06-12 19:31 ` Eric Sandeen
2018-06-12 19:45 ` Eric Sandeen
2018-06-12 19:31 ` [PATCH 3/7] mkfs: parameterize sysconfdir in mkfs.xfs.8 Eric Sandeen
` (5 subsequent siblings)
7 siblings, 1 reply; 20+ messages in thread
From: Eric Sandeen @ 2018-06-12 19:31 UTC (permalink / raw)
To: linux-xfs
Simple move with no changes, next patch will parameterize @sysconfdir@
Signed-off-by: Eric Sandeen <sandeen@redhat.com>
Signed-off-by: Eric Sandeen <sandeen@sandeen.net>
---
man/man8/Makefile | 8 +-
man/man8/mkfs.xfs.8 | 1015 ------------------------------------------------
man/man8/mkfs.xfs.8.in | 1015 ++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 1022 insertions(+), 1016 deletions(-)
delete mode 100644 man/man8/mkfs.xfs.8
create mode 100644 man/man8/mkfs.xfs.8.in
diff --git a/man/man8/Makefile b/man/man8/Makefile
index 36620da..08e5e0d 100644
--- a/man/man8/Makefile
+++ b/man/man8/Makefile
@@ -7,14 +7,20 @@ include $(TOPDIR)/include/builddefs
MAN_SECTION = 8
-MAN_PAGES = $(shell echo *.$(MAN_SECTION))
+MAN_PAGES = $(shell echo *.$(MAN_SECTION)) mkfs.xfs.8
MAN_DEST = $(PKG_MAN_DIR)/man$(MAN_SECTION)
LSRCFILES = $(MAN_PAGES)
default : $(MAN_PAGES)
+LDIRT = mkfs.xfs.8
+
include $(BUILDRULES)
+mkfs.xfs.8: mkfs.xfs.8.in
+ @echo " [SED] $@"
+ $(Q)$(SED) -e "s|@sysconfdir@|$(PKG_ETC_DIR)|g" < $< > $@
+
install : default
$(INSTALL) -m 755 -d $(MAN_DEST)
$(INSTALL_MAN)
diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8
deleted file mode 100644
index dcd95ad..0000000
--- a/man/man8/mkfs.xfs.8
+++ /dev/null
@@ -1,1015 +0,0 @@
-.TH mkfs.xfs 8
-.SH NAME
-mkfs.xfs \- construct an XFS filesystem
-.SH SYNOPSIS
-.B mkfs.xfs
-[
-.B \-c
-.I configuration
-] [
-[
-.B \-b
-.I block_size_options
-] [
-.B \-m
-.I global_metadata_options
-] [
-.B \-d
-.I data_section_options
-] [
-.B \-f
-] [
-.B \-i
-.I inode_options
-] [
-.B \-l
-.I log_section_options
-] [
-.B \-n
-.I naming_options
-] [
-.B \-p
-.I protofile
-] [
-.B \-q
-] [
-.B \-r
-.I realtime_section_options
-] [
-.B \-s
-.I sector_size_options
-] [
-.B \-L
-.I label
-] [
-.B \-N
-] [
-.B \-K
-]
-.I device
-.br
-.B mkfs.xfs \-V
-.SH DESCRIPTION
-.B mkfs.xfs
-constructs an XFS filesystem by writing on a special
-file using the values found in the arguments of the command line.
-It is invoked automatically by
-.BR mkfs (8)
-when it is given the
-.B \-t xfs
-option.
-.PP
-In its simplest (and most commonly used form), the size of the
-filesystem is determined from the disk driver. As an example, to make
-a filesystem with an internal log on the first partition on the first
-SCSI disk, use:
-.IP
-.B mkfs.xfs /dev/sda1
-.PP
-The metadata log can be placed on another device to reduce the number
-of disk seeks. To create a filesystem on the first partition on the
-first SCSI disk with a 10MiB log located on the first partition
-on the second SCSI disk, use:
-.RS
-.HP
-.B mkfs.xfs\ \-l\ logdev=/dev/sdb1,size=10m /dev/sda1
-.RE
-.PP
-Each of the
-.I option
-elements in the argument list above can be given as multiple comma-separated
-suboptions if multiple suboptions apply to the same option.
-Equivalently, each main option can be given multiple times with
-different suboptions.
-For example,
-.B \-l internal,size=10m
-and
-.B \-l internal \-l size=10m
-are equivalent.
-.PP
-In the descriptions below, sizes are given in sectors, bytes, blocks,
-kilobytes, megabytes, gigabytes, etc.
-Sizes are treated as hexadecimal if prefixed by 0x or 0X,
-octal if prefixed by 0, or decimal otherwise.
-The following lists possible multiplication suffixes:
-.RS
-.PD 0
-.HP
-.BR s "\ \-\ multiply by sector size (default = 512, see " \-s
-option below).
-.HP
-.BR b "\ \-\ multiply by filesystem block size (default = 4K, see " \-b
-option below).
-.HP
-.BR k "\ \-\ multiply by one kilobyte (1,024 bytes)."
-.HP
-.BR m "\ \-\ multiply by one megabyte (1,048,576 bytes)."
-.HP
-.BR g "\ \-\ multiply by one gigabyte (1,073,741,824 bytes)."
-.HP
-.BR t "\ \-\ multiply by one terabyte (1,099,511,627,776 bytes)."
-.HP
-.BR p "\ \-\ multiply by one petabyte (1,024 terabytes)."
-.HP
-.BR e "\ \-\ multiply by one exabyte (1,048,576 terabytes)."
-.PD
-.RE
-.PP
-When specifying parameters in units of sectors or filesystem blocks, the
-.B \-s
-option or the
-.B \-b
-option first needs to be added to the command line.
-Failure to specify the size of the units will result in illegal value errors
-when parameters are quantified in those units.
-.PP
-Many feature options allow an optional argument of 0 or 1, to explicitly
-disable or enable the functionality.
-.SH DEFAULT VALUES
-.BR mkfs.xfs (8)
-contains built-in default values for every option as described in the sections
-below.
-These built-in defaults may evolve over time as new capabilities are added.
-If the file
-.B /etc/xfs/mkfs/defaults
-exists, it will be parsed to override built-in defaults, and the defaults
-described in sections below may no longer apply.
-.PP
-The
-.B \-c
-option may also be used to specify an alternate configuration file
-as described in the OPTIONS section.
-.SH OPTIONS
-.TP
-.BI \-c " configuration"
-This option may be used to specify a configuration file other than
-.B /etc/xfs/mkfs/defaults
-to override selected built-in parameter defaults.
-If
-.B configuration
-is a full pathname or a relative pathname starting with
-.BR \'./\' " or " \'../\'
-then that explicit path to the configuration file will be used.
-Otherwise,
-.BR mkfs.xfs (8)
-will search for
-.B configuration
-first in the current working directory, and then in the
-.B /etc/xfs/mkfs/
-directory.
-See also the CONFIGURATION FILE FORMAT section below.
-.TP
-.BI \-b " block_size_options"
-This option specifies the fundamental block size of the filesystem.
-The valid
-.I block_size_option
-is:
-.RS 1.2i
-.TP
-.BI size= value
-The filesystem block size is specified with a
-.I value
-in bytes. The default value is 4096 bytes (4 KiB), the minimum is 512, and the
-maximum is 65536 (64 KiB).
-.IP
-To specify any options on the command line in units of filesystem blocks, this
-option must be specified first so that the filesystem block size is
-applied consistently to all options.
-.IP
-Although
-.B mkfs.xfs
-will accept any of these values and create a valid filesystem,
-XFS on Linux can only mount filesystems with pagesize or smaller blocks.
-.RE
-.TP
-.BI \-m " global_metadata_options"
-These options specify metadata format options that either apply to the entire
-filesystem or aren't easily characterised by a specific functionality group. The
-valid
-.I global_metadata_options
-are:
-.RS 1.2i
-.TP
-.BI crc= value
-This is used to create a filesystem which maintains and checks CRC information
-in all metadata objects on disk. The value is either 0 to disable the feature,
-or 1 to enable the use of CRCs.
-.IP
-CRCs enable enhanced error detection due to hardware issues, whilst the format
-changes also improves crash recovery algorithms and the ability of various tools
-to validate and repair metadata corruptions when they are found. The CRC
-algorithm used is CRC32c, so the overhead is dependent on CPU architecture as
-some CPUs have hardware acceleration of this algorithm. Typically the overhead
-of calculating and checking the CRCs is not noticeable in normal operation.
-.IP
-By default,
-.B mkfs.xfs
-will enable metadata CRCs.
-.TP
-.BI finobt= value
-This option enables the use of a separate free inode btree index in each
-allocation group. The value is either 0 to disable the feature, or 1 to create
-a free inode btree in each allocation group.
-.IP
-The free inode btree mirrors the existing allocated inode btree index which
-indexes both used and free inodes. The free inode btree does not index used
-inodes, allowing faster, more consistent inode allocation performance as
-filesystems age.
-.IP
-By default,
-.B mkfs.xfs
-will create free inode btrees for filesystems created with the (default)
-.B \-m crc=1
-option set. When the option
-.B \-m crc=0
-is used, the free inode btree feature is not supported and is disabled.
-.TP
-.BI uuid= value
-Use the given value as the filesystem UUID for the newly created filesystem.
-The default is to generate a random UUID.
-.TP
-.BI rmapbt= value
-This option enables the creation of a reverse-mapping btree index in each
-allocation group. The value is either 0 to disable the feature, or 1 to
-create the btree.
-.IP
-The reverse mapping btree maps filesystem blocks to the owner of the
-filesystem block. Most of the mappings will be to an inode number and an
-offset, though there will also be mappings to filesystem metadata. This
-secondary metadata can be used to validate the primary metadata or to
-pinpoint exactly which data has been lost when a disk error occurs.
-.IP
-By default,
-.B mkfs.xfs
-will not create reverse mapping btrees. This feature is only available
-for filesystems created with the (default)
-.B \-m crc=1
-option set. When the option
-.B \-m crc=0
-is used, the reverse mapping btree feature is not supported and is disabled.
-.TP
-.BI reflink= value
-This option enables the use of a separate reference count btree index in each
-allocation group. The value is either 0 to disable the feature, or 1 to create
-a reference count btree in each allocation group.
-.IP
-The reference count btree enables the sharing of physical extents between
-the data forks of different files, which is commonly known as "reflink".
-Unlike traditional Unix filesystems which assume that every inode and
-logical block pair map to a unique physical block, a reflink-capable
-XFS filesystem removes the uniqueness requirement, allowing up to four
-billion arbitrary inode/logical block pairs to map to a physical block.
-If a program tries to write to a multiply-referenced block in a file, the write
-will be redirected to a new block, and that file's logical-to-physical
-mapping will be changed to the new block ("copy on write"). This feature
-enables the creation of per-file snapshots and deduplication. It is only
-available for the data forks of regular files.
-.IP
-By default,
-.B mkfs.xfs
-will not create reference count btrees and therefore will not enable the
-reflink feature. This feature is only available for filesystems created with
-the (default)
-.B \-m crc=1
-option set. When the option
-.B \-m crc=0
-is used, the reference count btree feature is not supported and reflink is
-disabled.
-.RE
-.TP
-.BI \-d " data_section_options"
-These options specify the location, size, and other parameters of the
-data section of the filesystem. The valid
-.I data_section_options
-are:
-.RS 1.2i
-.TP
-.BI agcount= value
-This is used to specify the number of allocation groups. The data section
-of the filesystem is divided into allocation groups to improve the
-performance of XFS. More allocation groups imply that more parallelism
-can be achieved when allocating blocks and inodes. The minimum
-allocation group size is 16 MiB; the maximum size is just under 1 TiB.
-The data section of the filesystem is divided into
-.I value
-allocation groups (default value is scaled automatically based
-on the underlying device size).
-.TP
-.BI agsize= value
-This is an alternative to using the
-.B agcount
-suboption. The
-.I value
-is the desired size of the allocation group expressed in bytes
-(usually using the
-.BR m " or " g
-suffixes).
-This value must be a multiple of the filesystem block size, and
-must be at least 16MiB, and no more than 1TiB, and may
-be automatically adjusted to properly align with the stripe geometry.
-The
-.B agcount
-and
-.B agsize
-suboptions are mutually exclusive.
-.TP
-.BI cowextsize= value
-Set the copy-on-write extent size hint on all inodes created by
-.BR mkfs.xfs "."
-The value must be provided in units of filesystem blocks.
-If the value is zero, the default value (currently 32 blocks) will be used.
-Directories will pass on this hint to newly created children.
-.TP
-.BI name= value
-This can be used to specify the name of the special file containing
-the filesystem. In this case, the log section must be specified as
-.B internal
-(with a size, see the
-.B \-l
-option below) and there can be no real-time section.
-.TP
-.BI file[= value ]
-This is used to specify that the file given by the
-.B name
-suboption is a regular file. The
-.I value
-is either 0 or 1, with 1 signifying that the file is regular. This
-suboption is used only to make a filesystem image. If the
-.I value
-is omitted then 1 is assumed.
-.TP
-.BI size= value
-This is used to specify the size of the data section. This suboption
-is required if
-.B \-d file[=1]
-is given. Otherwise, it is only needed if the filesystem should occupy
-less space than the size of the special file.
-.TP
-.BI sunit= value
-This is used to specify the stripe unit for a RAID device or a
-logical volume. The
-.I value
-has to be specified in 512-byte block units. Use the
-.B su
-suboption to specify the stripe unit size in bytes. This suboption
-ensures that data allocations will be stripe unit aligned when the
-current end of file is being extended and the file size is larger
-than 512KiB. Also inode allocations and the internal log will be
-stripe unit aligned.
-.TP
-.BI su= value
-This is an alternative to using
-.B sunit.
-The
-.B su
-suboption is used to specify the stripe unit for a RAID device or a
-striped logical volume. The
-.I value
-has to be specified in bytes, (usually using the
-.BR m " or " g
-suffixes). This
-.I value
-must be a multiple of the filesystem block size.
-.TP
-.BI swidth= value
-This is used to specify the stripe width for a RAID device or a
-striped logical volume. The
-.I value
-has to be specified in 512-byte block units. Use the
-.B sw
-suboption to specify the stripe width size in bytes.
-This suboption is required if
-.B \-d sunit
-has been specified and it has to be a multiple of the
-.B \-d sunit
-suboption.
-.TP
-.BI sw= value
-suboption is an alternative to using
-.B swidth.
-The
-.B sw
-suboption is used to specify the stripe width for a RAID device or
-striped logical volume. The
-.I value
-is expressed as a multiplier of the stripe unit,
-usually the same as the number of stripe members in the logical
-volume configuration, or data disks in a RAID device.
-.IP
-When a filesystem is created on a logical volume device,
-.B mkfs.xfs
-will automatically query the logical volume for appropriate
-.B sunit
-and
-.B swidth
-values.
-.TP
-.BI noalign
-This option disables automatic geometry detection and creates the filesystem
-without stripe geometry alignment even if the underlying storage device provides
-this information.
-.TP
-.BI rtinherit= value
-If set, all inodes created by
-.B mkfs.xfs
-will be created with the realtime flag set.
-Directories will pass on this flag to newly created children.
-.TP
-.BI projinherit= value
-All inodes created by
-.B mkfs.xfs
-will be assigned this project quota id.
-Directories will pass on the project id to newly created children.
-.TP
-.BI extszinherit= value
-All inodes created by
-.B mkfs.xfs
-will have this extent size hint applied.
-The value must be provided in units of filesystem blocks.
-Directories will pass on this hint to newly created children.
-.RE
-.TP
-.B \-f
-Force overwrite when an existing filesystem is detected on the device.
-By default,
-.B mkfs.xfs
-will not write to the device if it suspects that there is a filesystem
-or partition table on the device already.
-.TP
-.BI \-i " inode_options"
-This option specifies the inode size of the filesystem, and other
-inode allocation parameters.
-The XFS inode contains a fixed-size part and a variable-size part.
-The variable-size part, whose size is affected by this option, can contain:
-directory data, for small directories;
-attribute data, for small attribute sets;
-symbolic link data, for small symbolic links;
-the extent list for the file, for files with a small number of extents;
-and the root of a tree describing the location of extents for the file,
-for files with a large number of extents.
-.IP
-The valid
-.I inode_options
-are:
-.RS 1.2i
-.TP
-.BI size= value " | perblock=" value
-The inode size is specified either as a
-.I value
-in bytes with
-.BR size=
-or as the number fitting in a filesystem block with
-.BR perblock= .
-The minimum (and default)
-.I value
-is 256 bytes without crc, 512 bytes with crc enabled.
-The maximum
-.I value
-is 2048 (2 KiB) subject to the restriction that
-the inode size cannot exceed one half of the filesystem block size.
-.IP
-XFS uses 64-bit inode numbers internally; however, the number of
-significant bits in an inode number
-is affected by filesystem geometry. In
-practice, filesystem size and inode size are the predominant factors.
-The Linux kernel (on 32 bit hardware platforms) and most applications
-cannot currently handle inode numbers greater than 32 significant bits,
-so if no inode size is given on the command line,
-.B mkfs.xfs
-will attempt to choose a size
-such that inode numbers will be < 32 bits. If an inode size
-is specified, or if a filesystem is sufficiently large,
-.B mkfs.xfs
-will warn if this will create inode numbers > 32 significant
-bits.
-.TP
-.BI maxpct= value
-This specifies the maximum percentage of space in the filesystem that
-can be allocated to inodes. The default
-.I value
-is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1%
-for filesystems over 50TB.
-.IP
-In the default inode allocation mode, inode blocks are chosen such
-that inode numbers will not exceed 32 bits, which restricts the inode
-blocks to the lower portion of the filesystem. The data block
-allocator will avoid these low blocks to accommodate the specified
-maxpct, so a high value may result in a filesystem with nothing but
-inodes in a significant portion of the lower blocks of the filesystem.
-(This restriction is not present when the filesystem is mounted with
-the
-.I "inode64"
-option on 64-bit platforms).
-.IP
-Setting the value to 0 means that essentially all of the filesystem
-can become inode blocks, subject to inode32 restrictions.
-.IP
-This value can be modified with
-.IR xfs_growfs(8) .
-.TP
-.BI align[= value ]
-This is used to specify that inode allocation is or is not aligned. The
-.I value
-is either 0 or 1, with 1 signifying that inodes are allocated aligned.
-If the
-.I value
-is omitted, 1 is assumed. The default is that inodes are aligned.
-Aligned inode access is normally more efficient than unaligned access;
-alignment must be established at the time the filesystem is created,
-since inodes are allocated at that time.
-This option can be used to turn off inode alignment when the
-filesystem needs to be mountable by a version of IRIX
-that does not have the inode alignment feature
-(any release of IRIX before 6.2, and IRIX 6.2 without XFS patches).
-.TP
-.BI attr= value
-This is used to specify the version of extended attribute inline
-allocation policy to be used. By default, this is 2, which uses an
-efficient algorithm for managing the available inline inode space
-between attribute and extent data.
-.IP
-The previous version 1, which has fixed regions for attribute and
-extent data, is kept for backwards compatibility with kernels older
-than version 2.6.16.
-.TP
-.BI projid32bit[= value ]
-This is used to enable 32bit quota project identifiers. The
-.I value
-is either 0 or 1, with 1 signifying that 32bit projid are to be enabled.
-If the value is omitted, 1 is assumed. (This default changed
-in release version 3.2.0.)
-.TP
-.BI sparse[= value ]
-Enable sparse inode chunk allocation. The
-.I value
-is either 0 or 1, with 1 signifying that sparse allocation is enabled.
-If the value is omitted, 1 is assumed. Sparse inode allocation is
-disabled by default. This feature is only available for filesystems
-formatted with
-.B \-m crc=1.
-.IP
-When enabled, sparse inode allocation allows the filesystem to allocate
-smaller than the standard 64-inode chunk when free space is severely
-limited. This feature is useful for filesystems that might fragment free
-space over time such that no free extents are large enough to
-accommodate a chunk of 64 inodes. Without this feature enabled, inode
-allocations can fail with out of space errors under severe fragmented
-free space conditions.
-.RE
-.TP
-.BI \-l " log_section_options"
-These options specify the location, size, and other parameters of the
-log section of the filesystem. The valid
-.I log_section_options
-are:
-.RS 1.2i
-.TP
-.BI agnum= value
-If the log is internal, allocate it in this AG.
-.TP
-.BI internal[= value ]
-This is used to specify that the log section is a piece of the data
-section instead of being another device or logical volume. The
-.I value
-is either 0 or 1, with 1 signifying that the log is internal. If the
-.I value
-is omitted, 1 is assumed.
-.TP
-.BI logdev= device
-This is used to specify that the log section should reside on the
-.I device
-separate from the data section. The
-.B internal=1
-and
-.B logdev
-options are mutually exclusive.
-.TP
-.BI size= value
-This is used to specify the size of the log section.
-.IP
-If the log is contained within the data section and
-.B size
-isn't specified,
-.B mkfs.xfs
-will try to select a suitable log size depending
-on the size of the filesystem. The actual logsize depends on the
-filesystem block size and the directory block size.
-.IP
-Otherwise, the
-.B size
-suboption is only needed if the log section of the filesystem
-should occupy less space than the size of the special file. The
-.I value
-is specified in bytes or blocks, with a
-.B b
-suffix meaning multiplication by the filesystem block size, as
-described above. The overriding minimum value for size is 512 blocks.
-With some combinations of filesystem block size, inode size,
-and directory block size, the minimum log size is larger than 512 blocks.
-.TP
-.BI version= value
-This specifies the version of the log. The current default is 2,
-which allows for larger log buffer sizes, as well as supporting
-stripe-aligned log writes (see the sunit and su options, below).
-.IP
-The previous version 1, which is limited to 32k log buffers and does
-not support stripe-aligned writes, is kept for backwards compatibility
-with very old 2.4 kernels.
-.TP
-.BI sunit= value
-This specifies the alignment to be used for log writes. The
-.I value
-has to be specified in 512-byte block units. Use the
-.B su
-suboption to specify the log stripe unit size in bytes.
-Log writes will be aligned on this boundary,
-and rounded up to this boundary.
-This gives major improvements in performance on some configurations
-such as software RAID5 when the
-.B sunit
-is specified as the filesystem block size.
-The equivalent byte value must be a multiple of the filesystem block
-size. Version 2 logs are automatically selected if the log
-.B sunit
-suboption is specified.
-.IP
-The
-.B su
-suboption is an alternative to using
-.B sunit.
-.TP
-.BI su= value
-This is used to specify the log stripe. The
-.I value
-has to be specified in bytes, (usually using the
-.BR s " or " b
-suffixes). This value must be a multiple of the filesystem block size.
-Version 2 logs are automatically selected if the log
-.B su
-suboption is specified.
-.TP
-.BI lazy-count= value
-This changes the method of logging various persistent counters
-in the superblock. Under metadata intensive workloads, these
-counters are updated and logged frequently enough that the superblock
-updates become a serialization point in the filesystem. The
-.I value
-can be either 0 or 1.
-.IP
-With
-.BR lazy-count=1 ,
-the superblock is not modified or logged on every change of the
-persistent counters. Instead, enough information is kept in
-other parts of the filesystem to be able to maintain the persistent
-counter values without needed to keep them in the superblock.
-This gives significant improvements in performance on some configurations.
-The default
-.I value
-is 1 (on) so you must specify
-.B lazy-count=0
-if you want to disable this feature for older kernels which don't support
-it.
-.RE
-.TP
-.BI \-n " naming_options"
-These options specify the version and size parameters for the naming
-(directory) area of the filesystem. The valid
-.I naming_options
-are:
-.RS 1.2i
-.TP
-.BI size= value
-The directory block size is specified with a
-.I value
-in bytes. The block size must be a power of 2 and cannot be less than the
-filesystem block size.
-The default size
-.I value
-for version 2 directories is 4096 bytes (4 KiB),
-unless the filesystem block size is larger than 4096,
-in which case the default
-.I value
-is the filesystem block size.
-For version 1 directories the block size is the same as the
-filesystem block size.
-.TP
-.BI version= value
-The naming (directory) version
-.I value
-can be either 2 or 'ci', defaulting to 2 if unspecified.
-With version 2 directories, the directory block size can be
-any power of 2 size from the filesystem block size up to 65536.
-.IP
-The
-.B version=ci
-option enables ASCII only case-insensitive filename lookup and version
-2 directories. Filenames are case-preserving, that is, the names
-are stored in directories using the case they were created with.
-.IP
-Note: Version 1 directories are not supported.
-.TP
-.BI ftype= value
-This feature allows the inode type to be stored in the directory
-structure so that the
-.BR readdir (3)
-and
-.BR getdents (2)
-do not need to look up the inode to determine the inode type.
-
-The
-.I value
-is either 0 or 1, with 1 signifying that filetype information
-will be stored in the directory structure. The default value is 1.
-
-When CRCs are enabled (the default), the ftype functionality is always
-enabled, and cannot be turned off.
-.IP
-.RE
-.TP
-.BI \-p " protofile"
-If the optional
-.BI \-p " protofile"
-argument is given,
-.B mkfs.xfs
-uses
-.I protofile
-as a prototype file and takes its directions from that file.
-The blocks and inodes specifiers in the
-.I protofile
-are provided for backwards compatibility, but are otherwise unused.
-The syntax of the protofile is defined by a number of tokens separated
-by spaces or newlines. Note that the line numbers are not part of the
-syntax but are meant to help you in the following discussion of the file
-contents.
-.nf
-.sp .8v
-.in +5
-\f71 /stand/\f1\f2diskboot\f1\f7
-2 4872 110
-3 d\-\-777 3 1
-4 usr d\-\-777 3 1
-5 sh \-\-\-755 3 1 /bin/sh
-6 ken d\-\-755 6 1
-7 $
-8 b0 b\-\-644 3 1 0 0
-9 c0 c\-\-644 3 1 0 0
-10 fifo p\-\-644 3 1
-11 slink l\-\-644 3 1 /a/symbolic/link
-12 : This is a comment line
-13 $
-14 $\f1
-.in -5
-.fi
-.IP
-Line 1 is a dummy string.
-(It was formerly the bootfilename.)
-It is present for backward
-compatibility; boot blocks are not used on SGI systems.
-.IP
-Note that some string of characters must be present as the first line of
-the proto file to cause it to be parsed correctly; the value
-of this string is immaterial since it is ignored.
-.IP
-Line 2 contains two numeric values (formerly the numbers of blocks and inodes).
-These are also merely for backward compatibility: two numeric values must
-appear at this point for the proto file to be correctly parsed,
-but their values are immaterial since they are ignored.
-.IP
-The lines 3 through 11 specify the files and directories you want to
-include in this filesystem. Line 3 defines the
-root directory. Other directories and
-files that you want in the filesystem
-are indicated by lines 4 through 6 and
-lines 8 through 10. Line 11 contains
-symbolic link syntax.
-.IP
-Notice the dollar sign
-.RB ( $ )
-syntax on line 7. This syntax directs the
-.B mkfs.xfs
-command to terminate the branch of the filesystem it
-is currently on and then continue
-from the directory specified by
-the next line, in this case line 8.
-It must be the last character
-on a line.
-The colon
-on line 12 introduces a comment; all characters up until the
-following newline are ignored.
-Note that this means you cannot
-have a file in a prototype file whose name contains a colon.
-The
-.B $
-on lines 13 and 14 end the process, since no additional
-specifications follow.
-.IP
-File specifications provide the following:
-.IP
- * file mode
-.br
- * user ID
-.br
- * group ID
-.br
- * the file's beginning contents
-.P
-.IP
-A 6-character string defines the mode for
-a file. The first character of this string
-defines the file type. The character range
-for this first character is
-.B \-bcdpl.
-A file may be a regular file, a block special file,
-a character special file, directory files, named
-pipes (first-in, first out files), and symbolic
-links.
-The second character of the mode string is
-used to specify setuserID mode, in which case
-it is
-.BR u .
-If setuserID mode is not specified, the second character is
-.BR \- .
-The third character of the mode string is
-used to specify the setgroupID mode, in which
-case it is
-.BR g .
-If setgroupID mode is not specified, the third character is
-.BR \- .
-The remaining characters of the mode string are
-a three digit octal number. This octal number
-defines the owner, group, and other read, write,
-and execute permissions for the file, respectively.
-For more information on file permissions, see the
-.BR chmod (1)
-command.
-.IP
-Following the mode character string are two
-decimal number tokens that specify the user and group IDs
-of the file's owner.
-.IP
-In a regular file, the next token specifies the
-pathname from which the contents and size of the
-file are copied.
-In a block or character special file, the next token
-are two decimal numbers that specify the major and minor
-device numbers.
-When a file is a symbolic link, the next token
-specifies the contents of the link.
-
-When the file is a directory, the
-.B mkfs.xfs
-command creates the entries
-.B dot
-(.) and
-.B dot-dot
-(..) and then reads the list of names and file specifications
-in a recursive manner for all of the entries
-in the directory. A scan of the protofile is
-always terminated with the dollar (
-.B $
-) token.
-.TP
-.B \-q
-Quiet option. Normally
-.B mkfs.xfs
-prints the parameters of the filesystem
-to be constructed;
-the
-.B \-q
-flag suppresses this.
-.TP
-.BI \-r " realtime_section_options"
-These options specify the location, size, and other parameters of the
-real-time section of the filesystem. The valid
-.I realtime_section_options
-are:
-.RS 1.2i
-.TP
-.BI rtdev= device
-This is used to specify the
-.I device
-which should contain the real-time section of the filesystem.
-The suboption value is the name of a block device.
-.TP
-.BI extsize= value
-This is used to specify the size of the blocks in the real-time
-section of the filesystem. This
-.I value
-must be a multiple of the filesystem block size. The minimum allowed
-size is the filesystem block size or 4 KiB (whichever is larger); the
-default size is the stripe width for striped volumes or 64 KiB for
-non-striped volumes; the maximum allowed size is 1 GiB. The real-time
-extent size should be carefully chosen to match the parameters of the
-physical media used.
-.TP
-.BI size= value
-This is used to specify the size of the real-time section.
-This suboption is only needed if the real-time section of the
-filesystem should occupy less space than the size of the partition
-or logical volume containing the section.
-.TP
-.BI noalign
-This option disables stripe size detection, enforcing a realtime device with no
-stripe geometry.
-.RE
-.TP
-.BI \-s " sector_size_options"
-This option specifies the fundamental sector size of the filesystem.
-The valid
-.I sector_size_option
-is:
-.RS 1.2i
-.TP
-.BI size= value
-The sector size is specified with a
-.I value
-in bytes. The default
-.I sector_size
-is 512 bytes. The minimum value for sector size is
-512; the maximum is 32768 (32 KiB). The
-.I sector_size
-must be a power of 2 size and cannot be made larger than the
-filesystem block size.
-.IP
-To specify any options on the command line in units of sectors, this
-option must be specified first so that the sector size is
-applied consistently to all options.
-.RE
-.TP
-.BI \-L " label"
-Set the filesystem
-.IR label .
-XFS filesystem labels can be at most 12 characters long; if
-.I label
-is longer than 12 characters,
-.B mkfs.xfs
-will not proceed with creating the filesystem. Refer to the
-.BR mount "(8) and " xfs_admin (8)
-manual entries for additional information.
-.TP
-.B \-N
-Causes the file system parameters to be printed out without really
-creating the file system.
-.TP
-.B \-K
-Do not attempt to discard blocks at mkfs time.
-.TP
-.B \-V
-Prints the version number and exits.
-.SH CONFIGURATION FILE FORMAT
-The optional default configuration file in
-.B /etc/xfs/mkfs/default
-as well as any alternate configuration file specified via the
-.B \-c
-option follow a simple ini-style format as shown below.
-Available options consist of a small subset of the parameters available
-via the
-.BR mkfs.xfs (8)
-command line.
-Currently all default parameters can only be either enabled or disabled,
-with a value of 1 to enable or 0 to disable.
-See below for a list of all supported configuration parameters and their
-current built-in default settings.
-.PP
-.BI [data]
-.br
-.BI noalign=0
-.PP
-.BI [inode]
-.br
-.BI align=1
-.br
-.BI projid32bit=1
-.br
-.BI sparse=0
-.PP
-.BI [log]
-.br
-.BI lazy-count=1
-.PP
-.BI [metadata]
-.br
-.BI crc=1
-.br
-.BI finobt=1
-.br
-.BI rmapbt=0
-.br
-.BI reflink=0
-.PP
-.BI [naming]
-.br
-.BI ftype=1
-.PP
-.BI [rtdev]
-.br
-.BI noalign=0
-.PP
-.SH SEE ALSO
-.BR xfs (5),
-.BR mkfs (8),
-.BR mount (8),
-.BR xfs_info (8),
-.BR xfs_admin (8).
-.SH BUGS
-With a prototype file, it is not possible to specify hard links.
diff --git a/man/man8/mkfs.xfs.8.in b/man/man8/mkfs.xfs.8.in
new file mode 100644
index 0000000..dcd95ad
--- /dev/null
+++ b/man/man8/mkfs.xfs.8.in
@@ -0,0 +1,1015 @@
+.TH mkfs.xfs 8
+.SH NAME
+mkfs.xfs \- construct an XFS filesystem
+.SH SYNOPSIS
+.B mkfs.xfs
+[
+.B \-c
+.I configuration
+] [
+[
+.B \-b
+.I block_size_options
+] [
+.B \-m
+.I global_metadata_options
+] [
+.B \-d
+.I data_section_options
+] [
+.B \-f
+] [
+.B \-i
+.I inode_options
+] [
+.B \-l
+.I log_section_options
+] [
+.B \-n
+.I naming_options
+] [
+.B \-p
+.I protofile
+] [
+.B \-q
+] [
+.B \-r
+.I realtime_section_options
+] [
+.B \-s
+.I sector_size_options
+] [
+.B \-L
+.I label
+] [
+.B \-N
+] [
+.B \-K
+]
+.I device
+.br
+.B mkfs.xfs \-V
+.SH DESCRIPTION
+.B mkfs.xfs
+constructs an XFS filesystem by writing on a special
+file using the values found in the arguments of the command line.
+It is invoked automatically by
+.BR mkfs (8)
+when it is given the
+.B \-t xfs
+option.
+.PP
+In its simplest (and most commonly used form), the size of the
+filesystem is determined from the disk driver. As an example, to make
+a filesystem with an internal log on the first partition on the first
+SCSI disk, use:
+.IP
+.B mkfs.xfs /dev/sda1
+.PP
+The metadata log can be placed on another device to reduce the number
+of disk seeks. To create a filesystem on the first partition on the
+first SCSI disk with a 10MiB log located on the first partition
+on the second SCSI disk, use:
+.RS
+.HP
+.B mkfs.xfs\ \-l\ logdev=/dev/sdb1,size=10m /dev/sda1
+.RE
+.PP
+Each of the
+.I option
+elements in the argument list above can be given as multiple comma-separated
+suboptions if multiple suboptions apply to the same option.
+Equivalently, each main option can be given multiple times with
+different suboptions.
+For example,
+.B \-l internal,size=10m
+and
+.B \-l internal \-l size=10m
+are equivalent.
+.PP
+In the descriptions below, sizes are given in sectors, bytes, blocks,
+kilobytes, megabytes, gigabytes, etc.
+Sizes are treated as hexadecimal if prefixed by 0x or 0X,
+octal if prefixed by 0, or decimal otherwise.
+The following lists possible multiplication suffixes:
+.RS
+.PD 0
+.HP
+.BR s "\ \-\ multiply by sector size (default = 512, see " \-s
+option below).
+.HP
+.BR b "\ \-\ multiply by filesystem block size (default = 4K, see " \-b
+option below).
+.HP
+.BR k "\ \-\ multiply by one kilobyte (1,024 bytes)."
+.HP
+.BR m "\ \-\ multiply by one megabyte (1,048,576 bytes)."
+.HP
+.BR g "\ \-\ multiply by one gigabyte (1,073,741,824 bytes)."
+.HP
+.BR t "\ \-\ multiply by one terabyte (1,099,511,627,776 bytes)."
+.HP
+.BR p "\ \-\ multiply by one petabyte (1,024 terabytes)."
+.HP
+.BR e "\ \-\ multiply by one exabyte (1,048,576 terabytes)."
+.PD
+.RE
+.PP
+When specifying parameters in units of sectors or filesystem blocks, the
+.B \-s
+option or the
+.B \-b
+option first needs to be added to the command line.
+Failure to specify the size of the units will result in illegal value errors
+when parameters are quantified in those units.
+.PP
+Many feature options allow an optional argument of 0 or 1, to explicitly
+disable or enable the functionality.
+.SH DEFAULT VALUES
+.BR mkfs.xfs (8)
+contains built-in default values for every option as described in the sections
+below.
+These built-in defaults may evolve over time as new capabilities are added.
+If the file
+.B /etc/xfs/mkfs/defaults
+exists, it will be parsed to override built-in defaults, and the defaults
+described in sections below may no longer apply.
+.PP
+The
+.B \-c
+option may also be used to specify an alternate configuration file
+as described in the OPTIONS section.
+.SH OPTIONS
+.TP
+.BI \-c " configuration"
+This option may be used to specify a configuration file other than
+.B /etc/xfs/mkfs/defaults
+to override selected built-in parameter defaults.
+If
+.B configuration
+is a full pathname or a relative pathname starting with
+.BR \'./\' " or " \'../\'
+then that explicit path to the configuration file will be used.
+Otherwise,
+.BR mkfs.xfs (8)
+will search for
+.B configuration
+first in the current working directory, and then in the
+.B /etc/xfs/mkfs/
+directory.
+See also the CONFIGURATION FILE FORMAT section below.
+.TP
+.BI \-b " block_size_options"
+This option specifies the fundamental block size of the filesystem.
+The valid
+.I block_size_option
+is:
+.RS 1.2i
+.TP
+.BI size= value
+The filesystem block size is specified with a
+.I value
+in bytes. The default value is 4096 bytes (4 KiB), the minimum is 512, and the
+maximum is 65536 (64 KiB).
+.IP
+To specify any options on the command line in units of filesystem blocks, this
+option must be specified first so that the filesystem block size is
+applied consistently to all options.
+.IP
+Although
+.B mkfs.xfs
+will accept any of these values and create a valid filesystem,
+XFS on Linux can only mount filesystems with pagesize or smaller blocks.
+.RE
+.TP
+.BI \-m " global_metadata_options"
+These options specify metadata format options that either apply to the entire
+filesystem or aren't easily characterised by a specific functionality group. The
+valid
+.I global_metadata_options
+are:
+.RS 1.2i
+.TP
+.BI crc= value
+This is used to create a filesystem which maintains and checks CRC information
+in all metadata objects on disk. The value is either 0 to disable the feature,
+or 1 to enable the use of CRCs.
+.IP
+CRCs enable enhanced error detection due to hardware issues, whilst the format
+changes also improves crash recovery algorithms and the ability of various tools
+to validate and repair metadata corruptions when they are found. The CRC
+algorithm used is CRC32c, so the overhead is dependent on CPU architecture as
+some CPUs have hardware acceleration of this algorithm. Typically the overhead
+of calculating and checking the CRCs is not noticeable in normal operation.
+.IP
+By default,
+.B mkfs.xfs
+will enable metadata CRCs.
+.TP
+.BI finobt= value
+This option enables the use of a separate free inode btree index in each
+allocation group. The value is either 0 to disable the feature, or 1 to create
+a free inode btree in each allocation group.
+.IP
+The free inode btree mirrors the existing allocated inode btree index which
+indexes both used and free inodes. The free inode btree does not index used
+inodes, allowing faster, more consistent inode allocation performance as
+filesystems age.
+.IP
+By default,
+.B mkfs.xfs
+will create free inode btrees for filesystems created with the (default)
+.B \-m crc=1
+option set. When the option
+.B \-m crc=0
+is used, the free inode btree feature is not supported and is disabled.
+.TP
+.BI uuid= value
+Use the given value as the filesystem UUID for the newly created filesystem.
+The default is to generate a random UUID.
+.TP
+.BI rmapbt= value
+This option enables the creation of a reverse-mapping btree index in each
+allocation group. The value is either 0 to disable the feature, or 1 to
+create the btree.
+.IP
+The reverse mapping btree maps filesystem blocks to the owner of the
+filesystem block. Most of the mappings will be to an inode number and an
+offset, though there will also be mappings to filesystem metadata. This
+secondary metadata can be used to validate the primary metadata or to
+pinpoint exactly which data has been lost when a disk error occurs.
+.IP
+By default,
+.B mkfs.xfs
+will not create reverse mapping btrees. This feature is only available
+for filesystems created with the (default)
+.B \-m crc=1
+option set. When the option
+.B \-m crc=0
+is used, the reverse mapping btree feature is not supported and is disabled.
+.TP
+.BI reflink= value
+This option enables the use of a separate reference count btree index in each
+allocation group. The value is either 0 to disable the feature, or 1 to create
+a reference count btree in each allocation group.
+.IP
+The reference count btree enables the sharing of physical extents between
+the data forks of different files, which is commonly known as "reflink".
+Unlike traditional Unix filesystems which assume that every inode and
+logical block pair map to a unique physical block, a reflink-capable
+XFS filesystem removes the uniqueness requirement, allowing up to four
+billion arbitrary inode/logical block pairs to map to a physical block.
+If a program tries to write to a multiply-referenced block in a file, the write
+will be redirected to a new block, and that file's logical-to-physical
+mapping will be changed to the new block ("copy on write"). This feature
+enables the creation of per-file snapshots and deduplication. It is only
+available for the data forks of regular files.
+.IP
+By default,
+.B mkfs.xfs
+will not create reference count btrees and therefore will not enable the
+reflink feature. This feature is only available for filesystems created with
+the (default)
+.B \-m crc=1
+option set. When the option
+.B \-m crc=0
+is used, the reference count btree feature is not supported and reflink is
+disabled.
+.RE
+.TP
+.BI \-d " data_section_options"
+These options specify the location, size, and other parameters of the
+data section of the filesystem. The valid
+.I data_section_options
+are:
+.RS 1.2i
+.TP
+.BI agcount= value
+This is used to specify the number of allocation groups. The data section
+of the filesystem is divided into allocation groups to improve the
+performance of XFS. More allocation groups imply that more parallelism
+can be achieved when allocating blocks and inodes. The minimum
+allocation group size is 16 MiB; the maximum size is just under 1 TiB.
+The data section of the filesystem is divided into
+.I value
+allocation groups (default value is scaled automatically based
+on the underlying device size).
+.TP
+.BI agsize= value
+This is an alternative to using the
+.B agcount
+suboption. The
+.I value
+is the desired size of the allocation group expressed in bytes
+(usually using the
+.BR m " or " g
+suffixes).
+This value must be a multiple of the filesystem block size, and
+must be at least 16MiB, and no more than 1TiB, and may
+be automatically adjusted to properly align with the stripe geometry.
+The
+.B agcount
+and
+.B agsize
+suboptions are mutually exclusive.
+.TP
+.BI cowextsize= value
+Set the copy-on-write extent size hint on all inodes created by
+.BR mkfs.xfs "."
+The value must be provided in units of filesystem blocks.
+If the value is zero, the default value (currently 32 blocks) will be used.
+Directories will pass on this hint to newly created children.
+.TP
+.BI name= value
+This can be used to specify the name of the special file containing
+the filesystem. In this case, the log section must be specified as
+.B internal
+(with a size, see the
+.B \-l
+option below) and there can be no real-time section.
+.TP
+.BI file[= value ]
+This is used to specify that the file given by the
+.B name
+suboption is a regular file. The
+.I value
+is either 0 or 1, with 1 signifying that the file is regular. This
+suboption is used only to make a filesystem image. If the
+.I value
+is omitted then 1 is assumed.
+.TP
+.BI size= value
+This is used to specify the size of the data section. This suboption
+is required if
+.B \-d file[=1]
+is given. Otherwise, it is only needed if the filesystem should occupy
+less space than the size of the special file.
+.TP
+.BI sunit= value
+This is used to specify the stripe unit for a RAID device or a
+logical volume. The
+.I value
+has to be specified in 512-byte block units. Use the
+.B su
+suboption to specify the stripe unit size in bytes. This suboption
+ensures that data allocations will be stripe unit aligned when the
+current end of file is being extended and the file size is larger
+than 512KiB. Also inode allocations and the internal log will be
+stripe unit aligned.
+.TP
+.BI su= value
+This is an alternative to using
+.B sunit.
+The
+.B su
+suboption is used to specify the stripe unit for a RAID device or a
+striped logical volume. The
+.I value
+has to be specified in bytes, (usually using the
+.BR m " or " g
+suffixes). This
+.I value
+must be a multiple of the filesystem block size.
+.TP
+.BI swidth= value
+This is used to specify the stripe width for a RAID device or a
+striped logical volume. The
+.I value
+has to be specified in 512-byte block units. Use the
+.B sw
+suboption to specify the stripe width size in bytes.
+This suboption is required if
+.B \-d sunit
+has been specified and it has to be a multiple of the
+.B \-d sunit
+suboption.
+.TP
+.BI sw= value
+suboption is an alternative to using
+.B swidth.
+The
+.B sw
+suboption is used to specify the stripe width for a RAID device or
+striped logical volume. The
+.I value
+is expressed as a multiplier of the stripe unit,
+usually the same as the number of stripe members in the logical
+volume configuration, or data disks in a RAID device.
+.IP
+When a filesystem is created on a logical volume device,
+.B mkfs.xfs
+will automatically query the logical volume for appropriate
+.B sunit
+and
+.B swidth
+values.
+.TP
+.BI noalign
+This option disables automatic geometry detection and creates the filesystem
+without stripe geometry alignment even if the underlying storage device provides
+this information.
+.TP
+.BI rtinherit= value
+If set, all inodes created by
+.B mkfs.xfs
+will be created with the realtime flag set.
+Directories will pass on this flag to newly created children.
+.TP
+.BI projinherit= value
+All inodes created by
+.B mkfs.xfs
+will be assigned this project quota id.
+Directories will pass on the project id to newly created children.
+.TP
+.BI extszinherit= value
+All inodes created by
+.B mkfs.xfs
+will have this extent size hint applied.
+The value must be provided in units of filesystem blocks.
+Directories will pass on this hint to newly created children.
+.RE
+.TP
+.B \-f
+Force overwrite when an existing filesystem is detected on the device.
+By default,
+.B mkfs.xfs
+will not write to the device if it suspects that there is a filesystem
+or partition table on the device already.
+.TP
+.BI \-i " inode_options"
+This option specifies the inode size of the filesystem, and other
+inode allocation parameters.
+The XFS inode contains a fixed-size part and a variable-size part.
+The variable-size part, whose size is affected by this option, can contain:
+directory data, for small directories;
+attribute data, for small attribute sets;
+symbolic link data, for small symbolic links;
+the extent list for the file, for files with a small number of extents;
+and the root of a tree describing the location of extents for the file,
+for files with a large number of extents.
+.IP
+The valid
+.I inode_options
+are:
+.RS 1.2i
+.TP
+.BI size= value " | perblock=" value
+The inode size is specified either as a
+.I value
+in bytes with
+.BR size=
+or as the number fitting in a filesystem block with
+.BR perblock= .
+The minimum (and default)
+.I value
+is 256 bytes without crc, 512 bytes with crc enabled.
+The maximum
+.I value
+is 2048 (2 KiB) subject to the restriction that
+the inode size cannot exceed one half of the filesystem block size.
+.IP
+XFS uses 64-bit inode numbers internally; however, the number of
+significant bits in an inode number
+is affected by filesystem geometry. In
+practice, filesystem size and inode size are the predominant factors.
+The Linux kernel (on 32 bit hardware platforms) and most applications
+cannot currently handle inode numbers greater than 32 significant bits,
+so if no inode size is given on the command line,
+.B mkfs.xfs
+will attempt to choose a size
+such that inode numbers will be < 32 bits. If an inode size
+is specified, or if a filesystem is sufficiently large,
+.B mkfs.xfs
+will warn if this will create inode numbers > 32 significant
+bits.
+.TP
+.BI maxpct= value
+This specifies the maximum percentage of space in the filesystem that
+can be allocated to inodes. The default
+.I value
+is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1%
+for filesystems over 50TB.
+.IP
+In the default inode allocation mode, inode blocks are chosen such
+that inode numbers will not exceed 32 bits, which restricts the inode
+blocks to the lower portion of the filesystem. The data block
+allocator will avoid these low blocks to accommodate the specified
+maxpct, so a high value may result in a filesystem with nothing but
+inodes in a significant portion of the lower blocks of the filesystem.
+(This restriction is not present when the filesystem is mounted with
+the
+.I "inode64"
+option on 64-bit platforms).
+.IP
+Setting the value to 0 means that essentially all of the filesystem
+can become inode blocks, subject to inode32 restrictions.
+.IP
+This value can be modified with
+.IR xfs_growfs(8) .
+.TP
+.BI align[= value ]
+This is used to specify that inode allocation is or is not aligned. The
+.I value
+is either 0 or 1, with 1 signifying that inodes are allocated aligned.
+If the
+.I value
+is omitted, 1 is assumed. The default is that inodes are aligned.
+Aligned inode access is normally more efficient than unaligned access;
+alignment must be established at the time the filesystem is created,
+since inodes are allocated at that time.
+This option can be used to turn off inode alignment when the
+filesystem needs to be mountable by a version of IRIX
+that does not have the inode alignment feature
+(any release of IRIX before 6.2, and IRIX 6.2 without XFS patches).
+.TP
+.BI attr= value
+This is used to specify the version of extended attribute inline
+allocation policy to be used. By default, this is 2, which uses an
+efficient algorithm for managing the available inline inode space
+between attribute and extent data.
+.IP
+The previous version 1, which has fixed regions for attribute and
+extent data, is kept for backwards compatibility with kernels older
+than version 2.6.16.
+.TP
+.BI projid32bit[= value ]
+This is used to enable 32bit quota project identifiers. The
+.I value
+is either 0 or 1, with 1 signifying that 32bit projid are to be enabled.
+If the value is omitted, 1 is assumed. (This default changed
+in release version 3.2.0.)
+.TP
+.BI sparse[= value ]
+Enable sparse inode chunk allocation. The
+.I value
+is either 0 or 1, with 1 signifying that sparse allocation is enabled.
+If the value is omitted, 1 is assumed. Sparse inode allocation is
+disabled by default. This feature is only available for filesystems
+formatted with
+.B \-m crc=1.
+.IP
+When enabled, sparse inode allocation allows the filesystem to allocate
+smaller than the standard 64-inode chunk when free space is severely
+limited. This feature is useful for filesystems that might fragment free
+space over time such that no free extents are large enough to
+accommodate a chunk of 64 inodes. Without this feature enabled, inode
+allocations can fail with out of space errors under severe fragmented
+free space conditions.
+.RE
+.TP
+.BI \-l " log_section_options"
+These options specify the location, size, and other parameters of the
+log section of the filesystem. The valid
+.I log_section_options
+are:
+.RS 1.2i
+.TP
+.BI agnum= value
+If the log is internal, allocate it in this AG.
+.TP
+.BI internal[= value ]
+This is used to specify that the log section is a piece of the data
+section instead of being another device or logical volume. The
+.I value
+is either 0 or 1, with 1 signifying that the log is internal. If the
+.I value
+is omitted, 1 is assumed.
+.TP
+.BI logdev= device
+This is used to specify that the log section should reside on the
+.I device
+separate from the data section. The
+.B internal=1
+and
+.B logdev
+options are mutually exclusive.
+.TP
+.BI size= value
+This is used to specify the size of the log section.
+.IP
+If the log is contained within the data section and
+.B size
+isn't specified,
+.B mkfs.xfs
+will try to select a suitable log size depending
+on the size of the filesystem. The actual logsize depends on the
+filesystem block size and the directory block size.
+.IP
+Otherwise, the
+.B size
+suboption is only needed if the log section of the filesystem
+should occupy less space than the size of the special file. The
+.I value
+is specified in bytes or blocks, with a
+.B b
+suffix meaning multiplication by the filesystem block size, as
+described above. The overriding minimum value for size is 512 blocks.
+With some combinations of filesystem block size, inode size,
+and directory block size, the minimum log size is larger than 512 blocks.
+.TP
+.BI version= value
+This specifies the version of the log. The current default is 2,
+which allows for larger log buffer sizes, as well as supporting
+stripe-aligned log writes (see the sunit and su options, below).
+.IP
+The previous version 1, which is limited to 32k log buffers and does
+not support stripe-aligned writes, is kept for backwards compatibility
+with very old 2.4 kernels.
+.TP
+.BI sunit= value
+This specifies the alignment to be used for log writes. The
+.I value
+has to be specified in 512-byte block units. Use the
+.B su
+suboption to specify the log stripe unit size in bytes.
+Log writes will be aligned on this boundary,
+and rounded up to this boundary.
+This gives major improvements in performance on some configurations
+such as software RAID5 when the
+.B sunit
+is specified as the filesystem block size.
+The equivalent byte value must be a multiple of the filesystem block
+size. Version 2 logs are automatically selected if the log
+.B sunit
+suboption is specified.
+.IP
+The
+.B su
+suboption is an alternative to using
+.B sunit.
+.TP
+.BI su= value
+This is used to specify the log stripe. The
+.I value
+has to be specified in bytes, (usually using the
+.BR s " or " b
+suffixes). This value must be a multiple of the filesystem block size.
+Version 2 logs are automatically selected if the log
+.B su
+suboption is specified.
+.TP
+.BI lazy-count= value
+This changes the method of logging various persistent counters
+in the superblock. Under metadata intensive workloads, these
+counters are updated and logged frequently enough that the superblock
+updates become a serialization point in the filesystem. The
+.I value
+can be either 0 or 1.
+.IP
+With
+.BR lazy-count=1 ,
+the superblock is not modified or logged on every change of the
+persistent counters. Instead, enough information is kept in
+other parts of the filesystem to be able to maintain the persistent
+counter values without needed to keep them in the superblock.
+This gives significant improvements in performance on some configurations.
+The default
+.I value
+is 1 (on) so you must specify
+.B lazy-count=0
+if you want to disable this feature for older kernels which don't support
+it.
+.RE
+.TP
+.BI \-n " naming_options"
+These options specify the version and size parameters for the naming
+(directory) area of the filesystem. The valid
+.I naming_options
+are:
+.RS 1.2i
+.TP
+.BI size= value
+The directory block size is specified with a
+.I value
+in bytes. The block size must be a power of 2 and cannot be less than the
+filesystem block size.
+The default size
+.I value
+for version 2 directories is 4096 bytes (4 KiB),
+unless the filesystem block size is larger than 4096,
+in which case the default
+.I value
+is the filesystem block size.
+For version 1 directories the block size is the same as the
+filesystem block size.
+.TP
+.BI version= value
+The naming (directory) version
+.I value
+can be either 2 or 'ci', defaulting to 2 if unspecified.
+With version 2 directories, the directory block size can be
+any power of 2 size from the filesystem block size up to 65536.
+.IP
+The
+.B version=ci
+option enables ASCII only case-insensitive filename lookup and version
+2 directories. Filenames are case-preserving, that is, the names
+are stored in directories using the case they were created with.
+.IP
+Note: Version 1 directories are not supported.
+.TP
+.BI ftype= value
+This feature allows the inode type to be stored in the directory
+structure so that the
+.BR readdir (3)
+and
+.BR getdents (2)
+do not need to look up the inode to determine the inode type.
+
+The
+.I value
+is either 0 or 1, with 1 signifying that filetype information
+will be stored in the directory structure. The default value is 1.
+
+When CRCs are enabled (the default), the ftype functionality is always
+enabled, and cannot be turned off.
+.IP
+.RE
+.TP
+.BI \-p " protofile"
+If the optional
+.BI \-p " protofile"
+argument is given,
+.B mkfs.xfs
+uses
+.I protofile
+as a prototype file and takes its directions from that file.
+The blocks and inodes specifiers in the
+.I protofile
+are provided for backwards compatibility, but are otherwise unused.
+The syntax of the protofile is defined by a number of tokens separated
+by spaces or newlines. Note that the line numbers are not part of the
+syntax but are meant to help you in the following discussion of the file
+contents.
+.nf
+.sp .8v
+.in +5
+\f71 /stand/\f1\f2diskboot\f1\f7
+2 4872 110
+3 d\-\-777 3 1
+4 usr d\-\-777 3 1
+5 sh \-\-\-755 3 1 /bin/sh
+6 ken d\-\-755 6 1
+7 $
+8 b0 b\-\-644 3 1 0 0
+9 c0 c\-\-644 3 1 0 0
+10 fifo p\-\-644 3 1
+11 slink l\-\-644 3 1 /a/symbolic/link
+12 : This is a comment line
+13 $
+14 $\f1
+.in -5
+.fi
+.IP
+Line 1 is a dummy string.
+(It was formerly the bootfilename.)
+It is present for backward
+compatibility; boot blocks are not used on SGI systems.
+.IP
+Note that some string of characters must be present as the first line of
+the proto file to cause it to be parsed correctly; the value
+of this string is immaterial since it is ignored.
+.IP
+Line 2 contains two numeric values (formerly the numbers of blocks and inodes).
+These are also merely for backward compatibility: two numeric values must
+appear at this point for the proto file to be correctly parsed,
+but their values are immaterial since they are ignored.
+.IP
+The lines 3 through 11 specify the files and directories you want to
+include in this filesystem. Line 3 defines the
+root directory. Other directories and
+files that you want in the filesystem
+are indicated by lines 4 through 6 and
+lines 8 through 10. Line 11 contains
+symbolic link syntax.
+.IP
+Notice the dollar sign
+.RB ( $ )
+syntax on line 7. This syntax directs the
+.B mkfs.xfs
+command to terminate the branch of the filesystem it
+is currently on and then continue
+from the directory specified by
+the next line, in this case line 8.
+It must be the last character
+on a line.
+The colon
+on line 12 introduces a comment; all characters up until the
+following newline are ignored.
+Note that this means you cannot
+have a file in a prototype file whose name contains a colon.
+The
+.B $
+on lines 13 and 14 end the process, since no additional
+specifications follow.
+.IP
+File specifications provide the following:
+.IP
+ * file mode
+.br
+ * user ID
+.br
+ * group ID
+.br
+ * the file's beginning contents
+.P
+.IP
+A 6-character string defines the mode for
+a file. The first character of this string
+defines the file type. The character range
+for this first character is
+.B \-bcdpl.
+A file may be a regular file, a block special file,
+a character special file, directory files, named
+pipes (first-in, first out files), and symbolic
+links.
+The second character of the mode string is
+used to specify setuserID mode, in which case
+it is
+.BR u .
+If setuserID mode is not specified, the second character is
+.BR \- .
+The third character of the mode string is
+used to specify the setgroupID mode, in which
+case it is
+.BR g .
+If setgroupID mode is not specified, the third character is
+.BR \- .
+The remaining characters of the mode string are
+a three digit octal number. This octal number
+defines the owner, group, and other read, write,
+and execute permissions for the file, respectively.
+For more information on file permissions, see the
+.BR chmod (1)
+command.
+.IP
+Following the mode character string are two
+decimal number tokens that specify the user and group IDs
+of the file's owner.
+.IP
+In a regular file, the next token specifies the
+pathname from which the contents and size of the
+file are copied.
+In a block or character special file, the next token
+are two decimal numbers that specify the major and minor
+device numbers.
+When a file is a symbolic link, the next token
+specifies the contents of the link.
+
+When the file is a directory, the
+.B mkfs.xfs
+command creates the entries
+.B dot
+(.) and
+.B dot-dot
+(..) and then reads the list of names and file specifications
+in a recursive manner for all of the entries
+in the directory. A scan of the protofile is
+always terminated with the dollar (
+.B $
+) token.
+.TP
+.B \-q
+Quiet option. Normally
+.B mkfs.xfs
+prints the parameters of the filesystem
+to be constructed;
+the
+.B \-q
+flag suppresses this.
+.TP
+.BI \-r " realtime_section_options"
+These options specify the location, size, and other parameters of the
+real-time section of the filesystem. The valid
+.I realtime_section_options
+are:
+.RS 1.2i
+.TP
+.BI rtdev= device
+This is used to specify the
+.I device
+which should contain the real-time section of the filesystem.
+The suboption value is the name of a block device.
+.TP
+.BI extsize= value
+This is used to specify the size of the blocks in the real-time
+section of the filesystem. This
+.I value
+must be a multiple of the filesystem block size. The minimum allowed
+size is the filesystem block size or 4 KiB (whichever is larger); the
+default size is the stripe width for striped volumes or 64 KiB for
+non-striped volumes; the maximum allowed size is 1 GiB. The real-time
+extent size should be carefully chosen to match the parameters of the
+physical media used.
+.TP
+.BI size= value
+This is used to specify the size of the real-time section.
+This suboption is only needed if the real-time section of the
+filesystem should occupy less space than the size of the partition
+or logical volume containing the section.
+.TP
+.BI noalign
+This option disables stripe size detection, enforcing a realtime device with no
+stripe geometry.
+.RE
+.TP
+.BI \-s " sector_size_options"
+This option specifies the fundamental sector size of the filesystem.
+The valid
+.I sector_size_option
+is:
+.RS 1.2i
+.TP
+.BI size= value
+The sector size is specified with a
+.I value
+in bytes. The default
+.I sector_size
+is 512 bytes. The minimum value for sector size is
+512; the maximum is 32768 (32 KiB). The
+.I sector_size
+must be a power of 2 size and cannot be made larger than the
+filesystem block size.
+.IP
+To specify any options on the command line in units of sectors, this
+option must be specified first so that the sector size is
+applied consistently to all options.
+.RE
+.TP
+.BI \-L " label"
+Set the filesystem
+.IR label .
+XFS filesystem labels can be at most 12 characters long; if
+.I label
+is longer than 12 characters,
+.B mkfs.xfs
+will not proceed with creating the filesystem. Refer to the
+.BR mount "(8) and " xfs_admin (8)
+manual entries for additional information.
+.TP
+.B \-N
+Causes the file system parameters to be printed out without really
+creating the file system.
+.TP
+.B \-K
+Do not attempt to discard blocks at mkfs time.
+.TP
+.B \-V
+Prints the version number and exits.
+.SH CONFIGURATION FILE FORMAT
+The optional default configuration file in
+.B /etc/xfs/mkfs/default
+as well as any alternate configuration file specified via the
+.B \-c
+option follow a simple ini-style format as shown below.
+Available options consist of a small subset of the parameters available
+via the
+.BR mkfs.xfs (8)
+command line.
+Currently all default parameters can only be either enabled or disabled,
+with a value of 1 to enable or 0 to disable.
+See below for a list of all supported configuration parameters and their
+current built-in default settings.
+.PP
+.BI [data]
+.br
+.BI noalign=0
+.PP
+.BI [inode]
+.br
+.BI align=1
+.br
+.BI projid32bit=1
+.br
+.BI sparse=0
+.PP
+.BI [log]
+.br
+.BI lazy-count=1
+.PP
+.BI [metadata]
+.br
+.BI crc=1
+.br
+.BI finobt=1
+.br
+.BI rmapbt=0
+.br
+.BI reflink=0
+.PP
+.BI [naming]
+.br
+.BI ftype=1
+.PP
+.BI [rtdev]
+.br
+.BI noalign=0
+.PP
+.SH SEE ALSO
+.BR xfs (5),
+.BR mkfs (8),
+.BR mount (8),
+.BR xfs_info (8),
+.BR xfs_admin (8).
+.SH BUGS
+With a prototype file, it is not possible to specify hard links.
--
1.8.3.1
^ permalink raw reply related [flat|nested] 20+ messages in thread* [PATCH 4/7] mkfs: tidy up whitespace in mkfs/config.c
2018-06-12 19:31 [PATCH 0/7] mkfs config support cleanups Eric Sandeen
` (2 preceding siblings ...)
2018-06-12 19:31 ` [PATCH 3/7] mkfs: parameterize sysconfdir in mkfs.xfs.8 Eric Sandeen
@ 2018-06-12 19:31 ` Eric Sandeen
2018-06-12 22:09 ` Darrick J. Wong
2018-06-12 19:31 ` [PATCH 5/7] mkfs: properly fix TOCTOU open/stat race in config file handling Eric Sandeen
` (3 subsequent siblings)
7 siblings, 1 reply; 20+ messages in thread
From: Eric Sandeen @ 2018-06-12 19:31 UTC (permalink / raw)
To: linux-xfs
Fix 80 col wraps, inconsistent whitespace, etc.
Signed-off-by: Eric Sandeen <sandeen@redhat.com>
Signed-off-by: Eric Sandeen <sandeen@sandeen.net>
---
mkfs/config.c | 98 ++++++++++++++++++++++++++++++---------------------------
mkfs/xfs_mkfs.c | 13 ++++----
2 files changed, 59 insertions(+), 52 deletions(-)
diff --git a/mkfs/config.c b/mkfs/config.c
index f7f40fc..f27e480 100644
--- a/mkfs/config.c
+++ b/mkfs/config.c
@@ -64,8 +64,9 @@ enum rtdev_subopts {
/* Just define the max options array size manually right now */
#define MAX_SUBOPTS 5
-static int config_check_bool(
- uint64_t value)
+static int
+config_check_bool(
+ uint64_t value)
{
if (value > 1)
goto out;
@@ -83,7 +84,7 @@ data_config_parser(
int psubopt,
uint64_t value)
{
- enum data_subopts subopt = psubopt;
+ enum data_subopts subopt = psubopt;
if (config_check_bool(value) != 0)
return -1;
@@ -102,7 +103,7 @@ inode_config_parser(
int psubopt,
uint64_t value)
{
- enum inode_subopts subopt = psubopt;
+ enum inode_subopts subopt = psubopt;
if (config_check_bool(value) != 0)
return -1;
@@ -127,7 +128,7 @@ log_config_parser(
int psubopt,
uint64_t value)
{
- enum log_subopts subopt = psubopt;
+ enum log_subopts subopt = psubopt;
if (config_check_bool(value) != 0)
return -1;
@@ -146,7 +147,7 @@ metadata_config_parser(
int psubopt,
uint64_t value)
{
- enum metadata_subopts subopt = psubopt;
+ enum metadata_subopts subopt = psubopt;
if (config_check_bool(value) != 0)
return -1;
@@ -176,7 +177,7 @@ naming_config_parser(
int psubopt,
uint64_t value)
{
- enum naming_subopts subopt = psubopt;
+ enum naming_subopts subopt = psubopt;
if (config_check_bool(value) != 0)
return -1;
@@ -195,7 +196,7 @@ rtdev_config_parser(
int psubopt,
uint64_t value)
{
- enum rtdev_subopts subopt = psubopt;
+ enum rtdev_subopts subopt = psubopt;
if (config_check_bool(value) != 0)
return -1;
@@ -209,11 +210,11 @@ rtdev_config_parser(
}
struct confopts {
- const char *name;
- const char *subopts[MAX_SUBOPTS];
- int (*parser)(struct mkfs_default_params *dft,
- int psubopt, uint64_t value);
- bool seen;
+ const char *name;
+ const char *subopts[MAX_SUBOPTS];
+ int (*parser)(struct mkfs_default_params *dft,
+ int psubopt, uint64_t value);
+ bool seen;
} confopts_tab[] = {
{
.name = "data",
@@ -392,17 +393,17 @@ parse_config_stream(
enum parse_line_type parse_type;
struct confopts *confopt = NULL;
int subopt;
- char *tag = NULL;
+ char *tag = NULL;
while ((linelen = getline(&line, &len, fp)) != -1) {
- char *ignore_value;
- char *p;
+ char *ignore_value;
+ char *p;
lineno++;
/*
- * tag is allocated for us by scanf(), it must freed only on any
- * successful parse of a section or tag-value pair.
+ * tag is allocated for us by scanf(), it must freed only on
+ * any successful parse of a section or tag-value pair.
*/
parse_type = parse_get_line_type(line, linelen, &tag, &value);
@@ -421,19 +422,22 @@ parse_config_stream(
case PARSE_SECTION:
confopt = get_confopts(tag);
if (!confopt) {
- fprintf(stderr, _("Invalid section on line %s:%zu : %s\n"),
- config_file, lineno, tag);
+ fprintf(stderr,
+_("Invalid section on line %s:%zu : %s\n"),
+ config_file, lineno, tag);
goto out_free_tag;
}
if (!confopt->subopts) {
- fprintf(stderr, _("Section not yet supported on line %s:%zu : %s\n"),
- config_file, lineno, tag);
+ fprintf(stderr,
+_("Section not yet supported on line %s:%zu : %s\n"),
+ config_file, lineno, tag);
goto out_free_tag;
}
if (confopt->seen) {
errno = EINVAL;
- fprintf(stderr, _("Section '%s' respecified\n"),
- tag);
+ fprintf(stderr,
+_("Section '%s' respecified\n"),
+ tag);
goto out_free_tag;
}
confopt->seen = true;
@@ -441,8 +445,9 @@ parse_config_stream(
break;
case PARSE_TAG_VALUE:
if (!confopt) {
- fprintf(stderr, _("No section specified yet on line %s:%zu : %s\n"),
- config_file, lineno, line);
+ fprintf(stderr,
+_("No section specified yet on line %s:%zu : %s\n"),
+ config_file, lineno, line);
goto out_free_tag;
}
@@ -475,8 +480,9 @@ parse_config_stream(
ret = confopt->parser(dft, subopt, value);
if (ret) {
errno = EINVAL;
- fprintf(stderr, _("Error parsine line %s:%zu : %s\n"),
- config_file, lineno, line);
+ fprintf(stderr,
+_("Error parsine line %s:%zu : %s\n"),
+ config_file, lineno, line);
goto out;
}
@@ -501,7 +507,7 @@ out_free_tag:
static int
config_stat_check(
- struct stat *sp)
+ struct stat *sp)
{
if (!S_ISREG(sp->st_mode)) {
errno = EINVAL;
@@ -523,12 +529,12 @@ config_stat_check(
*/
int
open_cli_config(
- int dirfd,
- const char *cli_config_file,
- char **fpath)
+ int dirfd,
+ const char *cli_config_file,
+ char **fpath)
{
- int fd = -1, len, ret;
- struct stat st;
+ int fd = -1, len, ret;
+ struct stat st;
fd = openat(AT_FDCWD, cli_config_file, O_NOFOLLOW, O_RDONLY);
if (fd < 0) {
@@ -544,8 +550,7 @@ open_cli_config(
if (fd < 0)
goto out;
- ret = fstatat(dirfd, cli_config_file, &st,
- AT_SYMLINK_NOFOLLOW);
+ ret = fstatat(dirfd, cli_config_file, &st, AT_SYMLINK_NOFOLLOW);
if (ret != 0)
goto err_out_close;
@@ -590,8 +595,8 @@ open_config_file(
struct mkfs_default_params *dft,
char **fpath)
{
- int dirfd, fd = -1, len, ret;
- struct stat st;
+ int dirfd, fd = -1, len, ret;
+ struct stat st;
*fpath = malloc(PATH_MAX);
if (!*fpath)
@@ -634,9 +639,10 @@ open_config_file(
out:
if (fd < 0) {
if (dft->type != DEFAULTS_BUILTIN) {
- fprintf(stderr, _("Unable to open %s config file: %s : %s\n"),
- default_type_str(dft->type), *fpath,
- strerror(errno));
+ fprintf(stderr,
+_("Unable to open %s config file: %s : %s\n"),
+ default_type_str(dft->type), *fpath,
+ strerror(errno));
free(*fpath);
exit(1);
}
@@ -657,12 +663,12 @@ err_out_close:
*/
int
parse_defaults_file(
- int fd,
- struct mkfs_default_params *dft,
- const char *config_file)
+ int fd,
+ struct mkfs_default_params *dft,
+ const char *config_file)
{
- FILE *fp;
- int ret;
+ FILE *fp;
+ int ret;
fp = fdopen(fd, "r");
if (!fp)
diff --git a/mkfs/xfs_mkfs.c b/mkfs/xfs_mkfs.c
index 022323a..be3094b 100644
--- a/mkfs/xfs_mkfs.c
+++ b/mkfs/xfs_mkfs.c
@@ -3780,7 +3780,8 @@ main(
switch (c) {
case 'c':
if (cli_config_file) {
- fprintf(stderr, _("respecification of configuration not allowed\n"));
+ fprintf(stderr,
+_("respecification of configuration not allowed\n"));
exit(1);
}
cli_config_file = optarg;
@@ -3795,10 +3796,10 @@ main(
if (fd >= 0) {
ret = parse_defaults_file(fd, &dft, config_file);
if (ret) {
- fprintf(stderr, _("Error parsing %s config file: %s : %s\n"),
- default_type_str(dft.type),
- config_file,
- strerror(errno));
+ fprintf(stderr,
+_("Error parsing %s config file: %s : %s\n"),
+ default_type_str(dft.type),
+ config_file, strerror(errno));
free(config_file);
close(fd);
exit(1);
@@ -3819,7 +3820,7 @@ main(
platform_getoptreset();
- while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
+ while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF){
switch (c) {
case 'c':
/* already validated and parsed, ignore */
--
1.8.3.1
^ permalink raw reply related [flat|nested] 20+ messages in thread