btrfs-man5(5)
-==============
+=============
NAME
----
2. filesystem features
-3. file attributes
+3. filesystem limits
-4. control device
+4. file attributes
+
+5. control device
MOUNT OPTIONS
options please refer to `mount`(8) manpage. The options are sorted alphabetically
(discarding the 'no' prefix).
+NOTE: most mount options apply to the whole filesystem and only options in the
+first mounted subvolume will take effect. This is due to lack of implementation
+and may change in the future. This means that (for example) you can't set
+per-subvolume 'nodatacow', 'nodatasum', or 'compress' using mount options. This
+should eventually be fixed, but it has proved to be difficult to implement
+correctly within the Linux VFS framework.
+
*acl*::
*noacl*::
(default: on)
+
WARNING: Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or
-≥ 3.13.4 will break up the ref-links of CoW data (for example files
+≥ 3.13.4 will break up the reflinks of COW data (for example files
copied with `cp --reflink`, snapshots or de-duplicated data).
This may cause considerable increase of space usage depending on the
-broken up ref-links.
+broken up reflinks.
*barrier*::
*nobarrier*::
(default: on)
+
Ensure that all IO write operations make it through the device cache and are stored
-permanently when the filesystem is at it's consistency checkpoint. This
+permanently when the filesystem is at its consistency checkpoint. This
typically means that a flush command is sent to the device that will
synchronize all pending data and ordinary metadata blocks, then writes the
superblock and issues another flush.
Control BTRFS file data compression. Type may be specified as 'zlib',
'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
+then compression will always be attempted, but the data may end up uncompressed
if the compression would make them larger.
+
Otherwise some simple heuristics are applied to detect an incompressible file.
*nodiscard*::
(default: off)
+
-Enable discarding of freed file blocks using the TRIM operation. This is useful
-for SSD devices, thinly provisioned LUNs or virtual machine images where the
-backing device understands the operation. Depending on support of the
-underlying device, the operation may severely hurt performance in case the TRIM
-operation is synchronous (eg. with SATA devices up to revision 3.0).
-+
+Enable discarding of freed file blocks. This is useful for SSD devices, thinly
+provisioned LUNs, or virtual machine images; however, every storage layer must
+support discard for it to work. if the backing device does not support
+asynchronous queued TRIM, then this operation can severely degrade performance,
+because a synchronous TRIM operation will be attempted instead. Queued TRIM
+requires newer than SATA revision 3.1 chipsets and devices.
+
+If it is not necessary to immediately discard freed blocks, then the `fstrim`
+tool can be used to discard all free blocks in a batch. Scheduling a TRIM
+during a period of low system activity will prevent latent interference with
+the performance of other operations. Also, a device may ignore the TRIM command
+if the range is too small, so running a batch discard has a greater probability
+of actually discarding the blocks.
+
If discarding is not necessary to be done at the block freeing time, there's
`fstrim`(8) tool that lets the filesystem discard all free blocks in a batch,
-possibly not much interfering with other operations. Also, the the device may
+possibly not much interfering with other operations. Also, the device may
ignore the TRIM command if the range is too small, so running the batch discard
can actually discard the blocks.
+
Don't use this option unless you really need it. The inode number limit
on 64bit system is 2^64^, which is practically enough for the whole filesystem
-lifetime. Due to implemention of linux VFS layer, the inode numbers on 32bit
+lifetime. Due to implementation of linux VFS layer, the inode numbers on 32bit
systems are only 32 bits wide. This lowers the limit significantly and makes
it possible to reach it. In such case, this mount option will help.
Alternatively, files with high inode numbers can be copied to a new subvolume
*subvol='path'*::
Mount subvolume from 'path' rather than the toplevel subvolume. The
-'path' is always treated as relative to the the toplevel subvolume.
+'path' is always treated as relative to the toplevel subvolume.
This mount option overrides the default subvolume set for the given filesystem.
*subvolid='subvolid'*::
+
reduced-size metadata for extent references, saves a few percent of metadata
+
+FILESYSTEM LIMITS
+-----------------
+
+maximum file name length::
+255
+
+maximum symlink target length::
+depends on the 'nodesize' value, for 4k it's 3949 bytes, for larger nodesize
+it's 4095
++
+The symlink target may not be a valid path, ie the path name components
+can exceed the limits, there's no content validation at `symlink`(3) creation.
+
+maximum number of inodes::
+2^64^ but depends on the available metadata space as the inodes are created
+dynamically
+
+inode numbers::
+minimum number: 256 (for subvolumes), regular files and directories: 257
+
+maximum file length::
+inherent limit of btrfs is 2^64^ (16 EiB) but the linux VFS limit is 2^63^ (8 EiB)
+
+maximum number of subvolumes::
+2^64^ but depends on the available metadata space, the space consumed by all
+subvolume metadata includes bookeeping of the shared extents can be large (MiB,
+GiB)
+
+maximum number of hardlinks of a file in a directory::
+65536 when the `extref` feature is turned on during mkfs (default), roughly
+100 otherwise
+
+
FILE ATTRIBUTES
---------------
The btrfs filesystem supports setting the following file attributes using the
'O_DSYNC'
*X*::
-'no compression', permanently turn off compression on the given file, other
-compression mount options will not affect that
+'no compression', permanently turn off compression on the given file. Any
+compression mount options will not affect this file.
+
When set on a directory, all newly created files will inherit this attribute.
projects / platform / upstream / btrfs-progs.git / blobdiff