title: xfs_io(8)

summary: debug the I/O path of an XFS filesystem

text:
# xfs_io(8)

## NAME
xfs_io - debug the I/O path of an XFS filesystem

## SYNOPSIS
xfs_io [ -adfimrRstxT ] [ -c cmd ] ... [ -C cmd ] ... [ -p prog ] [ file ]

xfs_io -V

## DESCRIPTION
xfs_io is a debugging tool like xfs_db(8), but is aimed at examining the regular file I/O paths rather than the raw XFS volume itself. These code paths include not only the obvious read/write/mmap interfaces for manipulating files, but also cover all of the XFS extensions (such as space preallocation, additional inode flags, etc).

## OPTIONS
xfs_io commands may be run interactively (the default) or as arguments on the command line. Interactive mode always runs commands on the current open file, whilst commands run from the command line may be repeated on all open files rather than just the current open file. In general, open file iteration will occur for commands that operate on file content or state. In contrast, commands that operate on filesystem or system-wide state will only be run on the current file regardless of how many files are currently open. Multiple arguments may be given on the command line and they are run in the sequence given. The program exits one all commands have been run.

-c cmd

Run the specified command on all currently open files. To maintain compatibility with historical usage, commands that can not be run on all open files will still be run but only execute once on the current open file. Multiple -c arguments may be given and may be interleaved on the command line in any order with -C commands.

-C cmd

Run the specified command only on the current open file. Multiple -C arguments may be given and may be interleaved on the command line in any order with -c commands.

-p prog

Set the program name for prompts and some error messages, the default value is xfs_io.

-f

Create file if it does not already exist.

-r

Open file read-only, initially. This is required if file is immutable or append-only.

-i

Start an idle thread. The purpose of this idle thread is to test io from a multi threaded process. With single threaded process, the file table is not shared and file structs are not reference counted. Spawning an idle thread can help detecting file struct reference leaks.

-x

Expert mode. Dangerous commands are only available in this mode. These commands also tend to require additional privileges.

-V

Prints the version number and exits.

The other open(2) options described below are also available from the command line.

## CONCEPTS
xfs_io maintains a number of open files and memory mappings. Files can be initially opened on the command line (optionally), and additional files can also be opened later.

xfs_io commands can be broken up into three groups. Some commands are aimed at doing regular file I/O - read, write, sync, space preallocation, etc.

The second set of commands exist for manipulating memory mapped regions of a file - mapping, accessing, storing, unmapping, flushing, etc.

The remaining commands are for the navigation and display of data structures relating to the open files, mappings, and the filesystems where they reside.

Many commands have extensive online help. Use the help command for more details on any command.

## FILE I/O COMMANDS
file [ N ]

Display a list of all open files and (optionally) switch to an alternate current open file.

open [[ -acdfrstRTPL ] path ]

Closes the current file, and opens the file specified by path instead. Without any arguments, displays statistics about the current file - see the stat command.

-a

opens append-only (O_APPEND).

-d

opens for direct I/O (O_DIRECT).

-f

creates the file if it doesn't already exist (O_CREAT).

-r

opens read-only (O_RDONLY).

-s

opens for synchronous I/O (O_SYNC).

-t

truncates on open (O_TRUNC).

-n

opens in non-blocking mode if possible (O_NONBLOCK).

-T

create a temporary file not linked into the filesystem namespace (O_TMPFILE). The pathname passed must refer to a directory which is treated as virtual parent for the newly created invisible file. Can not be used together with the -r option.

-R

marks the file as a realtime XFS file after opening it, if it is not already marked as such.

-P

opens the path as a referent only (O_PATH). This is incompatible with other flags specifying other O_xxx flags apart from -L.

-L

doesn't follow symlinks (O_NOFOLLOW). This is incompatible with other flags specifying other O_xxx flags apart from -P.

o

See the open command.

close

Closes the current open file, marking the next open file as current (if one exists).

c

See the close command.

chmod -r | -w

Change the mode of the currently open file. The -r option will set the file permissions to read-only (0444), whilst the -w option will set the file permissions to read-write (0644). This allows xfs_io to set up mismatches between the file permissions and the open file descriptor read/write mode to exercise permission checks inside various syscalls.

pread [ -b bsize ] [ -qUv ] [ -FBR [ -Z seed ] ] [ -V vectors ] offset length

Reads a range of bytes in a specified blocksize from the given offset.

-b

can be used to set the blocksize into which the read(2) requests will be split. The default blocksize is 4096 bytes.

-q

quiet mode, do not write anything to standard output.

-U

Perform the preadv2(2) call with RWF_DONTCACHE.

-v

dump the contents of the buffer after reading, by default only the count of bytes actually read is dumped.

-F

read the buffers in a forward sequential direction.

-B

read the buffers in a reverse sequential direction.

-R

read the buffers in the give range in a random order.

-Z seed

specify the random number seed used for random reads.

-V vectors

Use the vectored IO read syscall preadv(2) with a number of blocksize length iovecs. The number of iovecs is set by the vectors parameter.

r

See the pread command.

pwrite [ -i file ] [ -qAdDwNOUW ] [ -s skip ] [ -b size ] [ -S seed ] [ -FBR [ -Z zeed ] ] [ -V vectors ] offset length

Writes a range of bytes in a specified blocksize from the given offset. The bytes written can be either a set pattern or read in from another file before writing.

-i

allows an input file to be specified as the source of the data to be written.

-q

quiet mode, do not write anything to standard output.

-d

causes direct I/O, rather than the usual buffered I/O, to be used when reading the input file.

-w

call fdatasync(2) once all writes are complete (included in timing results)

-N

Perform the pwritev2(2) call with RWF_NOWAIT.

-D

Perform the pwritev2(2) call with RWF_DSYNC.

-A

Perform the pwritev2(2) call with RWF_ATOMIC.

-U

Perform the pwritev2(2) call with RWF_DONTCACHE.

-O

perform pwrite once and return the (maybe partial) bytes written.

-W

call fsync(2) once all writes are complete (included in timing results)

-s

specifies the number of bytes to skip from the start of the input file before starting to read.

-b

used to set the blocksize into which the write(2) requests will be split. The default blocksize is 4096 bytes.

-S

used to set the (repeated) fill pattern which is used when the data to write is not coming from a file. The default buffer fill pattern value is 0xcdcdcdcd.

-F

write the buffers in a forward sequential direction.

-B

write the buffers in a reverse sequential direction.

-R

write the buffers in the give range in a random order.

-Z seed

specify the random number seed used for random write

-V vectors

Use the vectored IO write syscall pwritev(2) with a number of blocksize length iovecs. The number of iovecs is set by the vectors parameter.

w

See the pwrite command.

bmap [ -adelpv ] [ -n nx ]

Prints the block mapping for the current open file. Refer to the xfs_bmap(8) manual page for complete documentation.

fiemap [ -alv ] [ -n nx ] [ offset [ len ]]

Prints the block mapping for the current open file using the fiemap ioctl. Options behave as described in the xfs_bmap(8) manual page.

Optionally, this command also supports passing the start offset from where to begin the mapping and the length of that region. The kernel will return any full extents which intersect with the requested range, and the fiemap command will print them in their entirety. If the requested range starts or ends in a hole, fiemap will print the hole, truncated to the requested range.

extsize [ -R | -D ] [ value ]

Display and/or modify the preferred extent size used when allocating space for the currently open file. If the -R option is specified, a recursive descent is performed for all directory entries below the currently open file (-D can be used to restrict the output to directories only). If the target file is a directory, then the inherited extent size is set for that directory (new files created in that directory inherit that extent size). The value should be specified in bytes, or using one of the usual units suffixes (k, m, g, b, etc). The extent size is always reported in units of bytes.

cowextsize [ -R | -D ] [ value ]

Display and/or modify the preferred copy-on-write extent size used when allocating space for the currently open file. If the -R option is specified, a recursive descent is performed for all directory entries below the currently open file (-D can be used to restrict the output to directories only). If the target file is a directory, then the inherited CoW extent size is set for that directory (new files created in that directory inherit that CoW extent size). The value should be specified in bytes, or using one of the usual units suffixes (k, m, g, b, etc). The extent size is always reported in units of bytes.

allocsp size 0

Sets the size of the file to size and zeroes any additional space allocated using the XFS_IOC_ALLOCSP/XFS_IOC_FREESP system call described in the xfsctl(3) manual page. allocsp and freesp do exactly the same thing. These commands are no longer supported as of Linux 5.17.

freesp size 0

See the allocsp command.

fadvise [ -r | -s | [[ -d | -n | -w ] offset length ]]

On platforms which support it, allows hints be given to the system regarding the expected I/O patterns on the file. The range arguments are required by some advise commands ([*] below), and the others must have no range arguments. With no arguments, the POSIX_FADV_NORMAL advice is implied (default readahead).

-d

the data will not be accessed again in the near future (POSIX_FADV_DONTNEED[*]).

-n

data will be accessed once and not be reused (POSIX_FADV_NOREUSE[*]).

-r

expect access to data in random order (POSIX_FADV_RANDOM), which sets readahead to zero.

-s

expect access to data in sequential order (POSIX_FADV_SEQUENTIAL), which doubles the default readahead on the file.

-w

advises the specified data will be needed again (POSIX_FADV_WILLNEED[*]) which forces the maximum readahead.

fdatasync

Calls fdatasync(2) to flush the file's in-core data to disk.

fsync

Calls fsync(2) to flush all in-core file state to disk.

s

See the fsync command.

sync_range [ -a | -b | -w ] offset length

On platforms which support it, allows control of syncing a range of the file to disk. With no options, SYNC_FILE_RANGE_WRITE is implied on the range supplied.

-a

wait for IO in the given range to finish after writing (SYNC_FILE_RANGE_WAIT_AFTER).

-b

wait for IO in the given range to finish before writing (SYNC_FILE_RANGE_WAIT_BEFORE).

-w

start writeback of dirty data in the given range (SYNC_FILE_RANGE_WRITE).

sync

Calls sync(2) to flush all filesystems' in-core data to disk.

syncfs

Calls syncfs(2) to flush this filesystem's in-core data to disk.

resvsp offset length

Allocates reserved, unwritten space for part of a file using the XFS_IOC_RESVSP system call described in the xfsctl(3) manual page.

unresvsp offset length

Frees reserved space for part of a file using the XFS_IOC_UNRESVSP system call described in the xfsctl(3) manual page.

falloc [ -k ] offset length

Allocates reserved, unwritten space for part of a file using the fallocate routine as described in the fallocate(2) manual page.

-k

will set the FALLOC_FL_KEEP_SIZE flag as described in fallocate(2).

fcollapse offset length

Call fallocate with FALLOC_FL_COLLAPSE_RANGE flag as described in the fallocate(2) manual page to de-allocates blocks and eliminates the hole created in this process by shifting data blocks into the hole.

finsert offset length

Call fallocate with FALLOC_FL_INSERT_RANGE flag as described in the fallocate(2) manual page to create the hole by shifting data blocks.

fpunch offset length

Punches (de-allocates) blocks in the file by calling fallocate with the FALLOC_FL_PUNCH_HOLE flag as described in the fallocate(2) manual page.

funshare offset length

Call fallocate with FALLOC_FL_UNSHARE_RANGE flag as described in the fallocate(2) manual page to unshare all shared blocks within the range.

fzero [ -k ] offset length

Call fallocate with FALLOC_FL_ZERO_RANGE flag as described in the fallocate(2) manual page to allocate and zero blocks within the range. With the -k option, use the FALLOC_FL_KEEP_SIZE flag as well.

fwzero offset length

Call fallocate with FALLOC_FL_WRITE_ZEROES flag as described in the fallocate(2) manual page to allocate and zero blocks within the range by submitting write zeroes.

zero offset length

Call xfsctl with XFS_IOC_ZERO_RANGE as described in the xfsctl(3) manual page to allocate and zero blocks within the range.

truncate offset

Truncates the current file at the given offset using ftruncate(2).

sendfile [ -q ] -i srcfile | -f N [ offset length ]

On platforms which support it, allows a direct in-kernel copy between two file descriptors. The current open file is the target, the source must be specified as another open file (-f) or by path (-i).

-q quiet mode, do not write anything to standard output.

readdir [ -v ] [ -o offset ] [ -l length ]

Read a range of directory entries from a given offset of a directory.

-v

verbose mode - dump dirent content as defined in readdir(3)

-o

specify starting offset

-l

specify total length to read (in bytes)

seek -a | -d | -h [ -r ] [ -s ] offset

On platforms that support the lseek(2) SEEK_DATA and SEEK_HOLE options, display the offsets of the specified segments.

-a

Display both data and hole segments starting at the specified offset.

-d

Display the data segment starting at the specified offset.

-h

Display the hole segment starting at the specified offset.

-r

Recursively display all the specified segments starting at the specified offset.

-s

Display the starting lseek(2) offset. This offset will be a calculated value when both data and holes are displayed together or performing a recusively display.

reflink [ -C ] [ -q ] src_file [src_offset dst_offset length]

On filesystems that support the FICLONERANGE or BTRFS_IOC_CLONE_RANGE ioctls, map length bytes at offset dst_offset in the open file to the same physical blocks that are mapped at offset src_offset in the file src_file , replacing any contents that may already have been there. If a program writes into a reflinked block range of either file, the dirty blocks will be cloned, written to, and remapped ("copy on write") in the affected file, leaving the other file(s) unchanged. If src_offset, dst_offset, and length are omitted, all contents of src_file will be reflinked into the open file.

-C

Print timing statistics in a condensed format.

-q

Do not print timing statistics at all.

dedupe [ -C ] [ -q ] src_file src_offset dst_offset length

On filesystems that support the FIDEDUPERANGE or BTRFS_IOC_FILE_EXTENT_SAME ioctls, map length bytes at offset dst_offset in the open file to the same physical blocks that are mapped at offset src_offset in the file src_file , but only if the contents of both ranges are identical. This is known as block-based deduplication. If a program writes into a reflinked block range of either file, the dirty blocks will be cloned, written to, and remapped ("copy on write") in the affected file, leaving the other file(s) unchanged.

-C

Print timing statistics in a condensed format.

-q

Do not print timing statistics at all.

copy_range [ -s src_offset ] [ -d dst_offset ] [ -l length ] src_file | -f N

On filesystems that support the copy_file_range(2) system call, copies data from the source file into the current open file. The source must be specified either by path (src_file) or as another open file (-f). If length is not specified, this command copies data from src_offset to the end of src_file into the dst_file at dst_offset.

-s

Copy data from src_file beginning from src_offset.

-d

Copy data into the open file beginning at dst_offset.

-l

Copy up to length bytes of data.

swapext donor_file

Swaps extent forks between files. The current open file is the target. The donor file is specified by path. Note that file data is not copied (file content moves with the fork(s)).

exchangerange [OPTIONS]donor_file

Exchanges contents between files. The current open file is the target. The donor file is specified by path. Note that file data is not copied (file content moves with the fork(s)). Options include:

-C

Print timing information in a condensed format.

-c

Exchange contents only if file2 has not changed.

-d dest_offset

Swap extents with open file beginning at dest_offset.

-f

Flush changed file data and file metadata to disk.

-l length

Swap up to length bytes of data.

-n

Perform all the parameter validation checks but don't change anything.

-s src_offset

Swap extents with donor file beginning at src_offset.

-t

Print timing information.

-w

Only exchange written ranges in the supplied file.

set_encpolicy [ -c mode ] [ -n mode ] [ -f flags ] [ -s log2_dusize ] [ -v version ] [ keyspec ]

On filesystems that support encryption, assign an encryption policy to the current file. keyspec is a hex string which specifies the encryption key to use. For v1 encryption policies, keyspec must be a 16-character hex string (8 bytes). For v2 policies, keyspec must be a 32-character hex string (16 bytes). If unspecified, an all-zeroes value is used.

-c mode

contents encryption mode (e.g. AES-256-XTS)

-n mode

filenames encryption mode (e.g. AES-256-CTS)

-f flags

policy flags (numeric)

-s log2_dusize

log2 of data unit size. Not supported by v1 policies.

-v version

policy version. Defaults to 1 or 2 depending on the length of keyspec; or to 1 if keyspec is unspecified.

get_encpolicy [ -1 ] [ -t ]

On filesystems that support encryption, display the encryption policy of the current file.

-1

Use only the old ioctl to get the encryption policy. This only works if the file has a v1 encryption policy.

-t

Test whether v2 encryption policies are supported. Prints "supported", "unsupported", or an error message.

add_enckey [ -d descriptor ] [ -k key_id ]

On filesystems that support encryption, add an encryption key to the filesystem containing the currently open file. By default, the raw key in binary (typically 64 bytes long) is read from standard input.

-d descriptor

key descriptor, as a 16-character hex string (8 bytes). If given, the key will be available for use by v1 encryption policies that use this descriptor. Otherwise, the key is added as a v2 policy key, and on success the resulting "key identifier" will be printed.

-k key_id

ID of kernel keyring key of type "fscrypt-provisioning". If given, the raw key will be taken from here rather than from standard input.

rm_enckey [ -a ] keyspec

On filesystems that support encryption, remove an encryption key from the filesystem containing the currently open file. keyspec is a hex string specifying the key to remove, as a 16-character "key descriptor" or a 32-character "key identifier".

-a

Remove the key for all users who have added it, not just the current user. This is a privileged operation.

enckey_status keyspec

On filesystems that support encryption, display the status of an encryption key. keyspec is a hex string specifying the key for which to display the status, as a 16-character "key descriptor" or a 32-character "key identifier".

lsattr [ -R | -D | -a | -v ]

List extended inode flags on the currently open file. If the -R option is specified, a recursive descent is performed for all directory entries below the currently open file (-D can be used to restrict the output to directories only). This is a depth first descent, it does not follow symlinks and it also does not cross mount points. The current inode flag letters are documented below. Please refer to the ioctl_xfs_fsgetxattr(2) documentation for more details about what they mean.

r

realtime file (XFS_XFLAG_REALTIME)

p

prealloc (XFS_XFLAG_PREALLOC)

i

immutable (XFS_XFLAG_IMMUTABLE)

a

append only (XFS_XFLAG_APPEND)

s

synchronous file writes (XFS_XFLAG_SYNC)

A

noatime (XFS_XFLAG_NOATIME)

d

nodump (XFS_XFLAG_NODUMP)

t

inherit realtime flag (XFS_XFLAG_RTINHERIT)"

P

inherit project id (XFS_XFLAG_PROJINHERIT)

n

no symlink creation (XFS_XFLAG_NOSYMLINKS)

e

extent size hint (XFS_XFLAG_EXTSIZE)

E

inherit extent size hint (XFS_XFLAG_EXTSZINHERIT)

f

nodefrag (XFS_XFLAG_NODEFRAG)

S

filestream allocator (XFS_XFLAG_FILESTREAM)

x

direct access persistent memory (XFS_XFLAG_DAX)

C

copy on write extent hint (XFS_XFLAG_COWEXTSIZE)

X

has extended attributes (XFS_XFLAG_HASATTR)

chattr [ -R | -D ] [ +/-riasAdtPneEfSxC ]

Change extended inode flags on the currently open file. The -R and -D options have the same meaning as above. See the lsattr command above for the list of inode flag letters.

flink path

Link the currently open file descriptor into the filesystem namespace.

stat [ -v|-r ]

Selected statistics from stat(2) and the XFS_IOC_GETXATTR system call on the current file. If the -v option is specified, the atime (last access), mtime (last modify), and ctime (last change) timestamps are also displayed. The -r option dumps raw fields from the stat structure.

statx [ -v|-r ][ -m basic | -m all | -m <mask> ][ -FD ]

Selected statistics from stat(2) and the XFS_IOC_GETXATTR system call on the current file.

-v

Show timestamps.

-r

Dump raw statx structure values.

-m basic

Set the field mask for the statx call to STATX_BASIC_STATS.

-m all

Set all bits in the field mask for the statx call except for STATX__RESERVED. If no -m arguments are specified, the default is STATX_BASIC_STATS and STATX_BTIME.

-m <mask>

Specify a numeric field mask for the statx call.

-m +value

Add this value to the statx field value. Values can be numeric, or they can be words describing the desired fields. See the help command output for a list of recognized words.

-m -value

Remove this value from the statx field value.

-m +value,-value

Add and remove multiple values from the statx field value.

-F

Force the attributes to be synced with the server.

-D

Don't sync attributes with the server.

chproj [ -R|-D ]

Modifies the project identifier associated with the current path. The -R option will recursively descend if the current path is a directory. The -D option will also recursively descend, only setting modifying projects on subdirectories. See the xfs_quota(8) manual page for more information about project identifiers.

lsproj [ -R|-D ]

Displays the project identifier associated with the current path. The -R and -D options behave as described above, in chproj.

parent [ -fpz ] [ -b bufsize ] [ -i ino ] [ -n name ] [ ino gen ]

By default this command prints out the parent inode numbers, inode generation numbers and basenames of all the hardlinks which point to the inode of the current file. If the optional ino and gen parameters are provided, they will be used to create a file handle on the same filesystem as the open file. The parents of the file represented by the handle will be reported instead of the open file.

-b

Use a buffer of this size to receive parent pointer records from the kernel.

-i

Only show parent pointer records containing this inode number.

-n

Only show parent pointer records containing this directory entry name.

-p

the output is similar to the default output except pathnames up to the mount-point are printed out instead of the component name.

-s

Print records in short format: ino/gen/namelen/name

-z

Print only the first path from the root.

utimes atime_sec atime_nsec mtime_sec mtime_nsec

The utimes command changes the atime and mtime of the current file. sec uses UNIX timestamp notation and is the seconds elapsed since 1970-01-01 00:00:00 UTC. nsec is the nanoseconds since the sec. This value needs to be in the range 0-999999999 with UTIME_NOW and UTIME_OMIT being exceptions. Each (sec, nsec) pair constitutes a single timestamp value.

startupdate [ -e]

Create a temporary clone of a file in which to stage file updates. The -e option creates an empty staging file.

cancelupdate

Abandon changes from a update staging file.

commitupdate [OPTIONS]

Commit changes from a update staging file to the real file.

-C

Print timing information in a condensed format.

-h

Only swap ranges in the update staging file that were actually written.

-k

Do not change file size.

-n

Check parameters without changing anything.

-q

Do not print timing information at all.

cachestat off len

Print page cache statistics for the given file range.

## MEMORY MAPPED I/O COMMANDS
mmap [ N | [[ -rwxS ] [-s size ] offset length ]]

With no arguments, mmap shows the current mappings. Specifying a single numeric argument N sets the current mapping. If two arguments are specified (a range specified by offset and length), a new mapping is created spanning the range, and the protection mode can be given as a combination of PROT_READ (-r), PROT_WRITE (-w), and PROT_EXEC (-x). The mapping will be created with the MAP_SHARED flag by default, or with the Linux specific (MAP_SYNC | MAP_SHARED_VALIDATE) flags if -S is given. -s size is used to do a mmap(size) && munmap(size) operation at first, try to reserve some extendible free memory space, if size is bigger than length parameter. But there's not guarantee that the memory after length ( up to size ) will stay free. e.g. "mmap -rw -s 8192 1024" will mmap 0 ~ 1024 bytes memory, but try to reserve 1024 ~ 8192 free space(no guarantee). This free space will helpful for "mremap 8192" without MREMAP_MAYMOVE flag.

mm

See the mmap command.

mremap [ -f <new_address> ] [ -m ] new_length

Changes the current mapping size to new_length. Whether the mapping may be moved is controlled by the flags passed; MREMAP_FIXED (-f), or MREMAP_MAYMOVE (-m). new_length specifies a page-aligned address to which the mapping must be moved. It can be set to 139946004389888, 4096k or 1g etc.

mrm

See the mremap command.

munmap

Unmaps the current memory mapping.

mu

See the munmap command.

mread [ -f | -v ] [ -r ] [ offset length ]

Accesses a segment of the current memory mapping, optionally dumping it to the standard output stream (with -v or -f option) for inspection. The accesses are performed sequentially from the start offset by default, but can also be done from the end backwards through the mapping if the -r option in specified. The two verbose modes differ only in the relative offsets they display, the -f option is relative to file start, whereas -v shows offsets relative to the start of the mapping.

mr

See the mread command.

mwrite [ -r ] [ -S seed ] [ offset length ]

Stores a byte into memory for a range within a mapping. The default stored value is 'X', repeated to fill the range specified, but this can be changed using the -S option. The memory stores are performed sequentially from the start offset by default, but can also be done from the end backwards through the mapping if the -r option in specified.

mw

See the mwrite command.

msync [ -i ] [ -a | -s ] [ offset length ]

Writes all modified copies of pages over the specified range (or entire mapping if no range specified) to their backing storage locations. Also, optionally invalidates (-i) so that subsequent references to the pages will be obtained from their backing storage locations (instead of cached copies). The flush can be done synchronously (-s) or asynchronously (-a).

ms

See the msync command.

madvise [ -d | -r | -s | -w ] [ offset length ]

Modifies page cache behavior when operating on the current mapping. The range arguments are required by some advise commands ([*] below). With no arguments, the POSIX_MADV_NORMAL advice is implied (default readahead).

-d

the pages will not be needed (POSIX_MADV_DONTNEED[*]).

-r

expect random page references (POSIX_MADV_RANDOM), which sets readahead to zero.

-s

expect sequential page references (POSIX_MADV_SEQUENTIAL), which doubles the default readahead on the file.

-w

advises the specified pages will be needed again (POSIX_MADV_WILLNEED[*]) which forces the maximum readahead.

mincore

Dumps a list of pages or ranges of pages that are currently in core, for the current memory mapping.

## FILESYSTEM COMMANDS
aginfo [ -a agno ]

Show information about or update the state of allocation groups.

-a

Act only on a specific allocation group.

bulkstat [ -a agno ] [ -d ] [ -e endino ] [ -m ] [ -n batchsize ] [ -q ] [ -s startino ] [ -v version"]

Display raw stat information about a bunch of inodes in an XFS filesystem. Options are as follows:

-a agno

Display only results from the given allocation group. If not specified, all results returned will be displayed.

-d

Print debugging information about call results.

-e endino

Stop displaying records when this inode number is reached. Defaults to stopping when the system call stops returning results.

-m

Include metadata directories in the output.

-n batchsize

Retrieve at most this many records per call. Defaults to 4,096.

-q

Run quietly. Does not parse or output retrieved bulkstat information.

-s startino

Display inode allocation records starting with this inode. Defaults to the first inode in the filesystem. If the given inode is not allocated, results will begin with the next allocated inode in the filesystem.

-v version

Use a particular version of the kernel interface. Currently supported versions are 1 and 5.

bulkstat_single [ -d ] [ -m ] [ -v version ] [ inum... | special... ]

Display raw stat information about individual inodes in an XFS filesystem. The -d, -m, and -v options are the same as the bulkstat command. Arguments must be inode numbers or any of the special values:

root

Display information about the root directory inode.

freeze

Suspend all write I/O requests to the filesystem of the current file. Only available in expert mode and requires privileges.

thaw

Undo the effects of a filesystem freeze operation. Only available in expert mode and requires privileges.

inject [ tag ]

Inject errors into a filesystem to observe filesystem behavior at specific points under adverse conditions. Without the tag argument, displays the list of error tags available. Only available in expert mode and requires privileges.

rginfo [ -r rgno ]

Show information about or update the state of realtime allocation groups.

-r

Act only on a specific realtime group.

resblks [ blocks ]

Get and/or set count of reserved filesystem blocks using the XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls. Note -- this can be useful for exercising out of space behavior. Only available in expert mode and requires privileges.

shutdown [ -f ]

Force the filesystem to shut down, preventing any further IO. XFS and other filesystems implement this functionality, although implementation details may differ slightly. Only available in expert mode and requires privileges.

By default, the filesystem will not attempt to flush completed transactions to disk before shutting down the filesystem. This simulates a disk failure or crash.

-f

Force the filesystem to flush all completed transactions to disk before shutting down, matching XFS behavior when critical corruption is encountered.

statfs [ -c ] [ -g ] [ -s ]

Report selected statistics on the filesystem where the current file resides. The default behavior is to enable all three reporting options:

-c

Display XFS_IOC_FSCOUNTERS summary counter data.

-g

Display XFS_IOC_FSGEOMETRY filesystem geometry data.

-s

Display statfs(2) data.

inode [ [ -n ] number ] [ -v ]

The inode command queries physical information about an inode. With no arguments, it will return 1 or 0, indicating whether or not any inode numbers greater than 32 bits are currently in use in the filesystem. If given an inode number as an argument, the command will return the same inode number if it is in use, or 0 if not. With -n number , the next used inode number after this number will be returned, or zero if the supplied inode number is the highest one in use. With -v the command will also report the number of bits (32 or 64) used by the inode number printed in the result; if no inode number was specified on the command line, the maximum possible inode number in the system will be printed along with its size.

inumbers [ -a agno ] [ -d ] [ -e endino ] [ -n batchsize ] [ -s startino ] [ -v version ]

Prints allocation information about groups of inodes in an XFS filesystem. Callers can use this information to figure out which inodes are allocated. Options are as follows:

-a agno

Display only results from the given allocation group. If not specified, all results returned will be displayed.

-d

Print debugging information about call results.

-e endino

Stop displaying records when this inode number is reached. Defaults to stopping when the system call stops returning results.

-n batchsize

Retrieve at most this many records per call. Defaults to 4,096.

-s startino

Display inode allocation records starting with this inode. Defaults to the first inode in the filesystem. If the given inode is not allocated, results will begin with the next allocated inode in the filesystem.

-v version

Use a particular version of the kernel interface. Currently supported versions are 1 and 5.

scrub type [ agnumber | rgnumber | ino gen | metapath [ rgnumber ] ]

Scrub internal XFS filesystem metadata. The type parameter specifies which type of metadata to scrub. For AG metadata, one AG number must be specified. For realtime group metadata, one rtgroup number must be specified. For file metadata, the scrub is applied to the open file unless the inode number and generation number are specified. For metapath, the name of a file or a raw number must be specified. If the metapath file is a per-rtgroup file, the group number must be specified.

scrubv [ -b NN ] [ -d ] [ -m oflags ] [ -r ] [ -v NN ] [ -w ms ] group [ agnumber | ino gen ]

Scrub a bunch of internal XFS filesystem metadata. The group parameter specifies which group of metadata to scrub. Valid groups are ag, agheader, inode, iscan, fs, probe, rtgroup, or summary. For ag and agheader metadata, one AG number must be specified. For inode metadata, the scrub is applied to the open file unless the inode number and generation number are specified. For rtgroup metadata, one rt group number must be specified.

-b NN

Inject scrub barriers into the vector stream at the given interval. Barriers abort vector processing if any previous scrub function found corruption.

-d

Enables debug mode.

-m

Fail scrub barriers if any of these scrub output flags are seen.

-r

Repair metadata if corruptions are found. This option requires expert mode.

-v NN

Force a particular API version. single selects XFS_SCRUB_METADATA (one-by-one). vector selects XFS_SCRUBV_METADATA (vectored). If no option is specified, vector mode will be used, with a fallback to single mode if the kernel doesn't recognize the vector mode ioctl.

-w us

Wait the given number of microseconds between each scrub function.

repair type [ agnumber | ino gen ]

Repair internal XFS filesystem metadata. The type parameter specifies which type of metadata to repair. For AG metadata, one AG number must be specified. For file metadata, the repair is applied to the open file unless the inode number and generation number are specified. The -R option can be specified to force rebuilding of a metadata structure.

label [ -c | -s label ]

On filesystems that support online label manipulation, get, set, or clear the filesystem label. With no options, print the current filesystem label. The -c option clears the filesystem label by setting it to the null string. The -s label option sets the filesystem label to label. If the label is longer than the filesystem will accept, xfs_io will print an error message. XFS filesystem labels can be at most 12 characters long.

fsmap [ -d | -l | -r ] [ -m | -v ] [ -n nx ] [ start ] [ end ]

Prints the mapping of disk blocks used by the filesystem hosting the current file. The map lists each extent used by files, allocation group metadata, journalling logs, and static filesystem metadata, as well as any regions that are unused. Each line of the listings takes the following form:

extent: major:minor [startblock..endblock]: owner startoffset..endoffset length Static filesystem metadata, allocation group metadata, btrees, journalling logs, and free space are marked by replacing the startoffset..endoffset with the appropriate marker. All blocks, offsets, and lengths are specified in units of 512-byte blocks, no matter what the filesystem's block size is. The optional start and end arguments can be used to constrain the output to a particular range of disk blocks. If these two options are specified, exactly one of -d, -l, or -r must also be set.

-d

Display only extents from the data device. This option only applies for XFS filesystems.

-l

Display only extents from the external log device. This option only applies to XFS filesystems.

-r

Display only extents from the realtime device. This option only applies to XFS filesystems.

-m

Display results in a machine readable format (CSV). This option is not compatible with the -v flag. The columns of the output are: extent number, device major, device minor, physical start, physical end, owner, offset start, offset end, length. The start, end, and length numbers are provided in units of 512b. The owner field is a special string that takes the form:

inode_%lld_data

for inode data.

inode_%lld_data_bmbt

for inode data extent maps.

inode_%lld_attr

for inode extended attribute data.

inode_%lld_attr_bmbt

for inode extended attribute extent maps.

special_%u:%u

for other filesystem metadata.

-n num_extents

If this option is given, fsmap obtains the extent list of the file in groups of num_extents extents. In the absence of -n, fsmap queries the system for extents in groups of 131,072 records.

-v

Shows verbose information. When this flag is specified, additional AG specific information is appended to each line in the following form:

agno (startagblock..endagblock) nblocks flags

A second -v option will print out the flags legend. This option is not compatible with the -m flag.

fsuuid

Print the mounted filesystem UUID.

sysfspath

Print the sysfs or debugfs path for the mounted filesystem. The -d option selects debugfs instead of sysfs.

getfsprops name [ names... ]

Retrieve the values of the given filesystem properties.

listfsprops [ -v ]

List all filesystem properties that have been stored in the filesystem. If the -v flag is specified, prints the values of the properties.

setfsprops name=value [ name=value... ]

Set the given filesystem properties to the specified values.

removefsprops name [ names... ]

Remove the given filesystem properties.

## OTHER COMMANDS
help [ command ]

Display a brief description of one or all commands.

print

Display a list of all open files and memory mapped regions. The current file and current mapping are distinguishable from any others.

p

See the print command.

quit

Exit xfs_io.

q

See the quit command.

log_writes -d device -m mark

Create a mark named mark in the dm-log-writes log specified by device. This is intended to be equivalent to the shell command: dmsetup message device 0 mark mark

lw

See the log_writes command.

crc32cselftest

Test the internal crc32c implementation to make sure that it computes results correctly.

## SEE ALSO
mkfs.xfs(8), xfsctl(3), xfs_bmap(8), xfs_db(8), xfs(5), fdatasync(2), fstat(2), fstatfs(2), fsync(2), ftruncate(2), futimens(3), mmap(2), msync(2), open(2), pread(2), pwrite(2), readdir(3), dmsetup(8).


package: xfsprogs

title: xfs_logprint(8)

summary: print the log of an XFS filesystem

text:
# xfs_logprint(8)

## NAME
xfs_logprint - print the log of an XFS filesystem

## SYNOPSIS
xfs_logprint [ options ] device

## DESCRIPTION
xfs_logprint prints the log of an XFS filesystem (see xfs(5)). The device argument is the pathname of the partition or logical volume containing the filesystem. The device can be a regular file if the -f option is used. The contents of the filesystem remain undisturbed. There are two major modes of operation in xfs_logprint.

One mode is better for filesystem operation debugging. It is called the transactional view and is enabled through the -t option. The transactional view prints only the portion of the log that pertains to recovery. In other words, it prints out complete transactions between the tail and the head. This view tries to display each transaction without regard to how they are split across log records.

The second mode starts printing out information from the beginning of the log. Some error blocks might print out in the beginning because the last log record usually overlaps the oldest log record. A message is printed when the physical end of the log is reached and when the logical end of the log is reached. A log record view is displayed one record at a time. Transactions that span log records may not be decoded fully.

## OPTIONS
-b

Extract and print buffer information. Only used in transactional view.

-c

Attempt to continue when an error is detected.

-C filename

Copy the log from the filesystem to the file filename. The log itself is not printed.

-d

Dump the log from front to end, printing where each log record is located on disk.

-D

Do not decode anything; just print data.

-e

Exit when an error is found in the log. Normally, xfs_logprint tries to continue and unwind from bad logs. However, sometimes it just dies in bad ways. Using this option prevents core dumps.

-f

Specifies that the filesystem image to be processed is stored in a regular file at device (see the mkfs.xfs(8) -d file option). This might happen if an image copy of a filesystem has been made into an ordinary file with xfs_copy(8).

-l logdev

External log device. Only for those filesystems which use an external log.

-i

Extract and print inode information. Only used in transactional view.

-q

Extract and print quota information. Only used in transactional view.

-n

Do not try and interpret log data; just interpret log header information.

-o

Also print buffer data in hex. Normally, buffer data is just decoded, so better information can be printed.

-s start-block

Override any notion of where to start printing.

-t

Print out the transactional view.

-v

Print "overwrite" data.

-V

Prints the version number and exits.

## SEE ALSO
mkfs.xfs(8), mount(8).


title: xfs_mdrestore(8)

text:
# xfs_mdrestore(8)

## NAME
xfs_mdrestore - restores an XFS metadump image to a filesystem image

## SYNOPSIS
xfs_mdrestore [ -gi ] [ -l logdev ] [ -r rtdev ] source target

xfs_mdrestore -i [ -l logdev ] [ -r rtdev ] source

xfs_mdrestore -V

## DESCRIPTION
xfs_mdrestore is a debugging tool that restores a metadata image generated by xfs_metadump(8) to a filesystem. The source argument specifies the location of the metadump image and the target argument specifies the destination for the filesystem image. If the source is -, then the metadata image is read from stdin. This allows the output of be another program such as a compression application to be redirected to xfs_mdrestore. The target can be either a file or a device.

xfs_mdrestore should not be used to restore metadata onto an existing filesystem unless you are completely certain the target can be destroyed.

## OPTIONS
-g

Shows restore progress on stdout.

-i

Shows metadump information on stdout. If no target is specified, exits after displaying information. Older metadumps man not include any descriptive information.

-l logdev

Metadump in v2 format can contain metadata dumped from an external log. In such a scenario, the user has to provide a device to which the log device contents from the metadump file are copied.

-r rtdev

Restore realtime device metadata to this device. This is only required for a metadump in v2 format.

-V

Prints the version number and exits.

## DIAGNOSTICS
xfs_mdrestore returns an exit code of 0 if all the metadata is successfully restored or 1 if an error occurs.

## SEE ALSO
xfs_metadump(8), xfs_repair(8), xfs(5)

## BUGS
Email bug reports to linux-xfs@vger.kernel.org.


title: xfs_metadump(8)

summary: copy XFS filesystem metadata to a file

text:
# xfs_metadump(8)

## NAME
xfs_metadump - copy XFS filesystem metadata to a file

## SYNOPSIS
xfs_metadump [ -aefFgow ] [ -m max_extents ] [ -l logdev ] [ -r rtdev ] [ -v version ] source target

xfs_metadump -V

## DESCRIPTION
xfs_metadump is a debugging tool that copies the metadata from an XFS filesystem to a file. The source argument must be the pathname of the device or file containing the XFS filesystem and the target argument specifies the destination file name. If target is -, then the output is sent to stdout. This allows the output to be redirected to another program such as a compression application.

xfs_metadump may only be used to copy unmounted filesystems, or read-only mounted filesystems.

xfs_metadump does not alter the source filesystem in any way. The target image is a contiguous (non-sparse) file containing all the filesystem's metadata and indexes to where the blocks were copied from.

By default, xfs_metadump obfuscates most file (regular file, directory and symbolic link) names and extended attribute names to allow the dumps to be sent without revealing confidential information. Extended attribute values are zeroed and no data is copied. The only exceptions are file or attribute names that are 4 or less characters in length. Also file names that span extents (this can only occur with the mkfs.xfs(8) options where -n size > -b size) are not obfuscated. Names between 5 and 8 characters in length inclusively are partially obfuscated.

xfs_metadump cannot obfuscate metadata in the filesystem log. Log recovery of an obfuscated metadump image may expose clear-text metadata and/or cause filesystem corruption in the restored image. It is recommended that the source filesystem first be mounted and unmounted, if possible, to ensure that the log is clean. A subsequent invocation of xfs_metadump will capture a clean log and obfuscate all metadata correctly.

If a metadump must be produced from a filesystem with a dirty log, it is recommended that obfuscation be turned off with -o option, if metadata such as filenames is not considered sensitive. If obfuscation is required on a metadump with a dirty log, please inform the recipient of the metadump image about this situation.

The contents of an external log device can be dumped only when using the v2 format. Metadump in v2 format can be generated by passing the "-v 2" option. Metadump in v2 format is generated by default if the filesystem has an external log and the metadump version to use is not explicitly mentioned.

xfs_metadump should not be used for any purposes other than for debugging and reporting filesystem problems. The most common usage scenario for this tool is when xfs_repair(8) fails to repair a filesystem and a metadump image can be sent for analysis.

The file generated by xfs_metadump can be restored to filesystem image (minus the data) using the xfs_mdrestore(8) tool.

## OPTIONS
-a

Copies entire metadata blocks. Normally, xfs_metadump will zero any stale bytes interspersed with in-use metadata. Use this option to copy full metadata blocks, to provide more debugging information for a corrupted filesystem. Note that the extra data will be unobfuscated.

-e

Stops the dump on a read error. Normally, it will ignore read errors and copy all the metadata that is accessible.

-f

Specifies that the filesystem image to be processed is stored in a regular file (see the mkfs.xfs -d file option). This can also happen if an image copy of a filesystem has been made into an ordinary file with xfs_copy(8).

-F

Specifies that we want to continue even if the superblock magic is not correct. If the source is truly not an XFS filesystem, the resulting image will be useless, and xfs_metadump may crash.

-g

Shows dump progress. This is sent to stdout if the target is a file or to stderr if the target is stdout.

-l logdev

For filesystems which use an external log, this specifies the device where the external log resides. If the v2 metadump format is selected, the contents of the external log will be copied to the metadump. The v2 metadump format will be selected automatically if this option is specified.

-m

Set the maximum size of an allowed metadata extent. Extremely large metadata extents are likely to be corrupt, and will be skipped if they exceed this value. The default size is 2097151 blocks.

-o

Disables obfuscation of file names and extended attributes.

-r rtdev

For filesystems that have a realtime section, this specifies the device where the realtime section resides. If the v2 metadump format is selected, the realtime group superblocks will be copied to the metadump. The v2 metadump format will be selected automatically if the filesystem contains realtime groups.

-v

The format of the metadump file to be produced. Valid values are 1 and 2. The default metadump format is 1.

-w

Prints warnings of inconsistent metadata encountered to stderr. Bad metadata is still copied.

-V

Prints the version number and exits.

## DIAGNOSTICS
xfs_metadump returns an exit code of 0 if all readable metadata is successfully copied or 1 if a write error occurs or a read error occurs and the -e option used.

## NOTES
As xfs_metadump copies metadata only, it does not matter if the source filesystem has a realtime section or not. If the filesystem has an external log, it is not copied. Internal logs are copied and any outstanding log transactions are not obfuscated if they contain names.

xfs_metadump is a shell wrapper around the xfs_db(8) metadump command.

## SEE ALSO
xfs_repair(8), xfs_mdrestore(8), xfs_freeze(8), xfs_db(8), xfs_copy(8), xfs(5)

## BUGS
Email bug reports to linux-xfs@vger.kernel.org.


title: xfs_mkfile(8)

summary: create an XFS file

text:
# xfs_mkfile(8)

## NAME
xfs_mkfile - create an XFS file

## SYNOPSIS
xfs_mkfile [ -v ] [ -n ] [ -p ] size[k|b|m|g] filename ...

xfs_mkfile -V

## DESCRIPTION
xfs_mkfile creates one or more files. The file is padded with zeroes by default. The default size is in bytes, but it can be flagged as kilobytes, blocks, megabytes, or gigabytes with the k, b, m, or g suffixes, respectively.

## OPTIONS
-v

Verbose. Report the names and sizes of created files.

-n

No bytes. Create a holey file - that is, do not write out any data, just seek to end of file and write a block.

-p

Preallocate. The file is preallocated, then overwritten with zeroes, then truncated to the desired size.

-V

Prints the version number and exits.


title: xfs_ncheck(8)

text:
# xfs_ncheck(8)

## NAME
xfs_ncheck - generate pathnames from i-numbers for XFS

## SYNOPSIS
xfs_ncheck [ -i ino ] ... [ -f ] [ -s ] [ -l logdev ] device

xfs_ncheck -V

## DESCRIPTION
xfs_ncheck with no -i arguments generates an inode number and pathname list of all files on the given filesystem. Names of directory files are followed by /.. The output is not sorted in any particular order. The filesystem to be examined is specified by the device argument, which should be the disk or volume device for the filesystem. Filesystems stored in files can also be checked, using the -f flag.

## OPTIONS
-f

Specifies that the filesystem image to be processed is stored in a regular file at device (see the mkfs.xfs -d file option). This might happen if an image copy of a filesystem has been made into an ordinary file.

-l logdev

Specifies the device where the filesystem's external log resides. Only for those filesystems which use an external log. See the mkfs.xfs -l option, and refer to xfs(5) for a detailed description of the XFS log.

-s

Limits the report to special files and files with setuserid mode. This option may be used to detect violations of security policy.

-i ino

Limits the report to only those files whose inode numbers follow. May be given multiple times to select multiple inode numbers.

-V

Prints the version number and exits.

If the filesystem is seriously corrupted, or very busy and looks like it is corrupt, a message of the form that would be generated by the xfs_db(8) "check" command may appear.

xfs_ncheck is only useful with XFS filesystems.

## SEE ALSO
mkfs.xfs(8), xfs(5).


title: xfs_property(8)

text:
# xfs_property(8)

## NAME
xfs_property - examine and edit properties about an XFS filesystem

## SYNOPSIS
xfs_property target get name...

xfs_property target list [ -v ]

xfs_property target set name=value...

xfs_property target remove name...

xfs_property -V

## DESCRIPTION
xfs_property retrieves, lists, sets, or removes properties of an XFS filesystem. Filesystem properties are root-controlled attributes set on the root directory of the filesystem to enable the system administrator to coordinate with userspace programs.

target is one of: the root directory of a mounted filesystem; a block device containing an XFS filesystem; or a regular file containing an XFS filesystem.

## OPTIONS
-V

Print the version number and exits.

## COMMANDS
get

name... Prints the values of the given filesystem properties.

list

Lists the names of all filesystem properties. If the -v flag is specified, prints the values as well.

set

name=value... Sets the given filesystem properties to the specified values and prints what was set.

remove

name... Unsets the given filesystem properties.

## FILESYSTEM PROPERTIES
Known filesystem properties for XFS are:

autofsck See xfs_scrub(8) for more information.


title: xfs_protofile(8)

text:
# xfs_protofile(8)

## NAME
xfs_protofile - create a protofile for use with mkfs.xfs

## SYNOPSIS
xfs_protofile path [ paths... ]

xfs_protofile -V

## DESCRIPTION
xfs_protofile walks a directory tree to generate a protofile. The protofile format is specified in the mkfs.xfs(8) manual page and is derived from 3rd edition Unix.

## OPTIONS
path

Create protofile directives to copy this path into the root directory. If the path is a directory, protofile directives will be emitted to replicate the entire subtree as a subtree of the root directory. If the path is a not a directory, protofile directives will be emitted to create the file as an entry in the root directory. The first path must resolve to a directory.

## BUGS
Filenames cannot contain spaces. Extended attributes are not copied into the filesystem.


title: xfs_quota(8)

summary: manage use of quota on XFS filesystems

text:
# xfs_quota(8)

## NAME
xfs_quota - manage use of quota on XFS filesystems

## SYNOPSIS
xfs_quota [ -x ] [ -f ] [ -p prog ] [ -c cmd ] ... [ -d project ] ... [ -D projects_file ] [ -P projid_file ] [ path ... ]

xfs_quota -V

## DESCRIPTION
xfs_quota is a utility for reporting and editing various aspects of filesystem quota.

The options to xfs_quota are:

-c cmd

xfs_quota commands may be run interactively (the default) or as arguments on the command line. Multiple -c arguments may be given. The commands are run in the sequence given, then the program exits.

-p prog

Set the program name for prompts and some error messages, the default value is xfs_quota.

-x

Enable expert mode. All of the administrative commands (see the ADMINISTRATOR COMMANDS section below) which allow modifications to the quota system are available only in expert mode.

-f

Enable foreign filesystem mode. A limited number of user and administrative commands are available for use on some foreign (non-XFS) filesystems.

-d project

Project names or numeric identifiers may be specified with this option, which restricts the output of the individual xfs_quota commands to the set of projects specified. Multiple -d arguments may be given.

-D projects_file

Specify a file containing the mapping of numeric project identifiers to directory trees. /etc/projects as default, if this option is none.

-P projid_file

Specify a file containing the mapping of numeric project identifiers to project names. /etc/projid as default, if this option is none.

-V

Prints the version number and exits.

The optional path argument(s) can be used to specify mount points or device files which identify XFS filesystems. The output of the individual xfs_quota commands will then be restricted to the set of filesystems specified.

This manual page is divided into two sections - firstly, information for users of filesystems with quota enabled, and the xfs_quota commands of interest to such users; and then information which is useful only to administrators of XFS filesystems using quota and the quota commands which allow modifications to the quota system.

Note that common to almost all of the individual commands described below are the options for specifying which quota types are of interest - user quota (-u), group quota (-g), and/or project quota (-p). Also, several commands provide options to operate on "blocks used" (-b), "inodes used" (-i), and/or "realtime blocks used" (-r).

Many commands also have extensive online help. Use the help command for more details on any command.

## QUOTA OVERVIEW
In most computing environments, disk space is not infinite. The quota subsystem provides a mechanism to control usage of disk space. Quotas can be set for each individual user on any/all of the local filesystems. The quota subsystem warns users when they exceed their allotted limit, but allows some extra space for current work (hard limit/soft limit). In addition, XFS filesystems with limit enforcement turned off can be used as an effective disk usage accounting system.

### Users' View of Disk Quotas
To most users, disk quotas are either of no concern or a fact of life that cannot be avoided. There are two possible quotas that can be imposed - a limit can be set on the amount of space a user can occupy, and there may be a limit on the number of files (inodes) they can own.

The quota command provides information on the quotas that have been set by the system administrators and current usage.

There are four numbers for each limit: current usage, soft limit (quota), hard limit, and time limit. The soft limit is the number of 1K-blocks (or files) that the user is expected to remain below. The hard limit cannot be exceeded. If a user's usage reaches the hard limit, further requests for space (or attempts to create a file) fail with the "Quota exceeded" (EDQUOT) error.

When a user exceeds the soft limit, the timer is enabled. Any time the quota drops below the soft limits, the timer is disabled. If the timer pops, the particular limit that has been exceeded is treated as if the hard limit has been reached, and no more resources are allocated to the user. The only way to reset this condition, short of turning off limit enforcement or increasing the limit, is to reduce usage below quota. Only the superuser (i.e. a sufficiently capable process) can set the time limits and this is done on a per filesystem basis.

### Surviving When the Quota Limit Is Reached
In most cases, the only way for a user to recover from over-quota conditions is to abort whatever activity is in progress on the filesystem that has reached its limit, remove sufficient files to bring the limit back below quota, and retry the failed program.

However, if a user is in the editor and a write fails because of an over quota situation, that is not a suitable course of action. It is most likely that initially attempting to write the file has truncated its previous contents, so if the editor is aborted without correctly writing the file, not only are the recent changes lost, but possibly much, or even all, of the contents that previously existed.

There are several possible safe exits for a user caught in this situation. They can use the editor shell escape command to examine their file space and remove surplus files. Alternatively, using sh(1), they can suspend the editor, remove some files, then resume it. A third possibility is to write the file to some other filesystem (perhaps to a file on /tmp) where the user's quota has not been exceeded. Then after rectifying the quota situation, the file can be moved back to the filesystem it belongs on.

### Default Quotas
The XFS quota subsystem allows a default quota to be enforced for any user, group or project which does not have a quota limit explicitly set. These limits are stored in and displayed as ID 0's limits, although they do not actually limit ID 0.

## USER COMMANDS
print

Lists all paths with devices/project identifiers. The path list can come from several places - the command line, the mount table, and the /etc/projects file.

df

See the free command.

quota [ -g | -p | -u ] [ -bir ] [ -hnNv ] [ -f file ] [ ID | name ] ...

Show individual usage and limits, for a single user name or numeric user ID. The -h option reports in a "human-readable" format similar to the df(1) command. The -n option reports the numeric IDs rather than the name. The -N option omits the header. The -v option outputs verbose information. The -f option sends the output to file instead of stdout.

free [ -bir ] [ -hN ] [ -f file ]

Reports filesystem usage, much like the df(1) utility. It can show usage for blocks, inode, and/or realtime block space, and shows used, free, and total available. If project quota are in use (see the DIRECTORY TREE QUOTA section below), it will also report utilisation for those projects (directory trees). The -h option reports in a "human-readable" format. The -N option omits the header. The -f option outputs the report to file instead of stdout.

help [ command ]

Online help for all commands, or one specific command.

quit

Exit xfs_quota.

q

See the quit command.

## QUOTA ADMINISTRATION
The XFS quota system differs to that of other filesystems in a number of ways. Most importantly, XFS considers quota information as filesystem metadata and uses journaling to provide a higher level guarantee of consistency. As such, it is administered differently, in particular:

1.

The quotacheck command has no effect on XFS filesystems. The first time quota accounting is turned on (at mount time), XFS does an automatic quotacheck internally; afterwards, the quota system will always be completely consistent until quotas are manually turned off.

2.

There is no need for quota file(s) in the root of the XFS filesystem.

3.

XFS distinguishes between quota accounting and limit enforcement. Quota accounting must be turned on at the time of mounting the XFS filesystem. However, it is possible to turn on/off limit enforcement any time quota accounting is turned on. The "quota" option to the mount command turns on both (user) quota accounting and enforcement. The "uqnoenforce" option must be used to turn on user accounting with limit enforcement disabled.

4.

Turning on quotas on the root filesystem is slightly different from the above. For Linux XFS, the quota mount flags must be passed in with the "rootflags=" boot parameter.

5.

It is useful to use the state to monitor the XFS quota subsystem at various stages - it can be used to see if quotas are turned on, and also to monitor the space occupied by the quota system itself..

6.

There is a mechanism built into xfsdump that allows quota limit information to be backed up for later restoration, should the need arise.

7.

Quota limits cannot be set before turning on quotas on.

8.

XFS filesystems keep quota accounting on the superuser (user ID zero), and the tool will display the superuser's usage information. However, limits are never enforced on the superuser (nor are they enforced for group and project ID zero).

9.

XFS filesystems perform quota accounting whether the user has quota limits or not.

10.

XFS supports the notion of project quota, which can be used to implement a form of directory tree quota (i.e. to restrict a directory tree to only being able to use up a component of the filesystems available space; or simply to keep track of the amount of space used, or number of inodes, within the tree).

## ADMINISTRATOR COMMANDS
path [ N ]

Lists all paths with devices/project identifiers or set the current path to the Nth list entry (the current path is used by many of the commands described here, it identifies the filesystem toward which a command is directed). The path list can come from several places - the command line, the mount table, and the /etc/projects file.

report [ -gpu ] [ -bir ] [ -ahntlLNU ] [ -f file ]

Report filesystem quota information. This reports all quota usage for a filesystem, for the specified quota type (u/g/p and/or blocks/inodes/realtime). It reports blocks in 1KB units by default. The -h option reports in a "human-readable" format similar to the df(1) command. The -f option outputs the report to file instead of stdout. The -a option reports on all filesystems. By default, outputs the name of the user/group/project. If no name is defined for a given ID, outputs the numeric ID instead. The -n option outputs the numeric ID instead of the name. The -L and -U options specify lower and/or upper ID bounds to report on. If upper/lower bounds are specified, then by default only the IDs will be displayed in output; with the -l option, a lookup will be performed to translate these IDs to names. The -N option reports information without the header line. The -t option performs a terse report.

state [ -gpu ] [ -av ] [ -f file ]

Report overall quota state information. This reports on the state of quota accounting, quota enforcement, and the number of extents being used by quota metadata within the filesystem. The -f option outputs state information to file instead of stdout. The -a option reports state on all filesystems and not just the current path.

limit [ -g | -p | -u ] bsoft=N | bhard=N | isoft=N | ihard=N | rtbsoft=N | rtbhard=N -d | id | name

Set quota block limits (bhard/bsoft), inode count limits (ihard/isoft) and/or realtime block limits (rtbhard/rtbsoft) to N, where N is a number representing bytes or inodes. For block limits, a number with a s/b/k/m/g/t/p/e multiplication suffix as described in mkfs.xfs(8) is also accepted. For inode limits, no suffixes are allowed. The -d option (defaults) can be used to set the default value that will be used, otherwise a specific user/group/project name or numeric identifier must be specified.

timer [ -g | -p | -u ] [ -bir ] value [ -d | id | name ]

Allows the quota enforcement timeout (i.e. the amount of time allowed to pass before the soft limits are enforced as the hard limits) to be modified. The current timeout setting can be displayed using the state command.

When setting the default timer via the -d option, or for id 0, or if no argument is given after value the value argument is a number of seconds indicating the relative amount of time after soft limits are exceeded, before hard limits are enforced.

When setting any other individual timer by id or name, the value is the number of seconds from now, at which time the hard limits will be enforced. This allows extending the grace time of an individual user who has exceeded soft limits.

For value, units of 'minutes', 'hours', 'days', and 'weeks' are also understood (as are their abbreviations 'm', 'h', 'd', and 'w').

warn [ -g | -p | -u ] [ -bir ] value -d | id | name

Allows the quota warnings limit (i.e. the number of times a warning will be send to someone over quota) to be viewed and modified. The -d option (defaults) can be used to set the default time that will be used, otherwise a specific user/group/project name or numeric identifier must be specified. NOTE: this feature is not currently implemented.

enable [ -gpu ] [ -v ]

Switches on quota enforcement for the filesystem identified by the current path. This requires the filesystem to have been mounted with quota enabled, and for accounting to be currently active. The -v option (verbose) displays the state after the operation has completed.

disable [ -gpu ] [ -v ]

Disables quota enforcement, while leaving quota accounting active. The -v option (verbose) displays the state after the operation has completed.

off [ -gpu ] [ -v ]

Permanently switches quota off for the filesystem identified by the current path. Quota can only be switched back on subsequently by unmounting and then mounting again.

remove [ -gpu ] [ -v ]

Remove any space allocated to quota metadata from the filesystem identified by the current path. Quota must not be enabled on the filesystem, else this operation will report an error.

dump [ -g | -p | -u ] [ -L | -U ] [ -f file ]

Dump out quota limit information for backup utilities, either to standard output (default) or to a file. The -L and -U options specify lower and/or upper ID bounds to dump. This is only the limits, not the usage information, of course.

restore [ -g | -p | -u ] [ -f file ]

Restore quota limits from a backup file. The file must be in the format produced by the dump command.

quot [ -g | -p | -u ] [ -bir ] [ -acnv ] [ -f file ]

Summarize filesystem ownership, by user, group or project. This command uses a special XFS "bulkstat" interface to quickly scan an entire filesystem and report usage information. This command can be used even when filesystem quota are not enabled, as it is a full-filesystem scan (it may also take a long time...). The -a option displays information on all filesystems. The -c option displays a histogram instead of a report. The -n option displays numeric IDs rather than names. The -v option displays verbose information. The -f option send the output to file instead of stdout.

project [ -cCs [ -d depth ] [ -p path ] id | name ]

The -c, -C, and -s options allow the directory tree quota mechanism to be maintained. -d allows one to limit recursion level when processing project directories and -p allows one to specify project paths at command line ( instead of /etc/projects ). All options are discussed in detail below.

## DIRECTORY TREE QUOTA
The project quota mechanism in XFS can be used to implement a form of directory tree quota, where a specified directory and all of the files and subdirectories below it (i.e. a tree) can be restricted to using a subset of the available space in the filesystem.

A managed tree must be setup initially using the -s option to the project command. The specified project name or identifier is matched to one or more trees defined in /etc/projects, and these trees are then recursively descended to mark the affected inodes as being part of that tree. This process sets an inode flag and the project identifier on every file in the affected tree. Once this has been done, new files created in the tree will automatically be accounted to the tree based on their project identifier. An attempt to create a hard link to a file in the tree will only succeed if the project identifier matches the project identifier for the tree. The xfs_io utility can be used to set the project ID for an arbitrary file, but this can only be done by a privileged user.

A previously setup tree can be cleared from project quota control through use of the project -C option, which will recursively descend the tree, clearing the affected inodes from project quota control.

Finally, the project -c option can be used to check whether a tree is setup, it reports nothing if the tree is correct, otherwise it reports the paths of inodes which do not have the project ID of the rest of the tree, or if the inode flag is not set.

Option -d can be used to limit recursion level (-1 is infinite, 0 is top level only, 1 is first level ... ). Option -p adds possibility to specify project paths in command line without a need for /etc/projects to exist. Note that if projects file exists then it is also used.

## EXAMPLES
Enabling quota enforcement on an XFS filesystem (restrict a user to a set amount of space).

```
# mount -o uquota /dev/xvm/home /home
# xfs_quota -x -c 'limit bsoft=500m bhard=550m tanya' /home
# xfs_quota -x -c report /home
```

Enabling project quota on an XFS filesystem (restrict files in log file directories to only using 1 gigabyte of space).

```
# mount -o prjquota /dev/xvm/var /var
# echo 42:/var/log >> /etc/projects
# echo logfiles:42 >> /etc/projid
# xfs_quota -x -c 'project -s logfiles' /var
# xfs_quota -x -c 'limit -p bhard=1g logfiles' /var
```

Same as above without a need for configuration files.

```
# rm -f /etc/projects /etc/projid
# mount -o prjquota /dev/xvm/var /var
# xfs_quota -x -c 'project -s -p /var/log 42' /var
# xfs_quota -x -c 'limit -p bhard=1g 42' /var
```

## CAVEATS
The XFS allocation mechanism will always reserve the maximum amount of space required before proceeding with an allocation. If insufficient space for this reservation is available, due to the block quota limit being reached for example, this may result in the allocation failing even though there is sufficient space. Quota enforcement can thus sometimes happen in situations where the user is under quota and the end result of some operation would still have left the user under quota had the operation been allowed to run its course. This additional overhead is typically in the range of tens of blocks.

Both of these properties are unavoidable side effects of the way XFS operates, so should be kept in mind when assigning block limits.

## BUGS
Quota support for filesystems with realtime subvolumes is not yet implemented, nor is the quota warning mechanism (the Linux warnquota(8) tool can be used to provide similar functionality on that platform).

## FILES
/etc/projects

Mapping of numeric project identifiers to directories trees.

/etc/projid

Mapping of numeric project identifiers to project names.

## SEE ALSO
df(1), mount(1), sync(2), projid(5), projects(5). xfs(5). warnquota(8),


title: xfs_repair(8)

summary: repair an XFS filesystem

text:
# xfs_repair(8)

## NAME
xfs_repair - repair an XFS filesystem

## SYNOPSIS
xfs_repair [ -dfLPv ] [ -n | -e ] [ -m maxmem ] [ -c subopt=value ] [ -o subopt[=value] ] [ -t interval ] [ -l logdev ] [ -r rtdev ] device

xfs_repair -V

## DESCRIPTION
xfs_repair repairs corrupt or damaged XFS filesystems (see xfs(5)). The filesystem is specified using the device argument which should be the device name of the disk partition or volume containing the filesystem. If given the name of a block device, xfs_repair will attempt to find the raw device associated with the specified block device and will use the raw device instead.

Regardless, the filesystem to be repaired must be unmounted, otherwise, the resulting filesystem may be inconsistent or corrupt.

## OPTIONS
-f

Specifies that the filesystem image to be processed is stored in a regular file at device (see the mkfs.xfs -d file option). This might happen if an image copy of a filesystem has been copied or written into an ordinary file. This option implies that any external log or realtime section is also in an ordinary file.

-L

Force Log Zeroing. Forces xfs_repair to zero the log even if it is dirty (contains metadata changes). When using this option the filesystem will likely appear to be corrupt, and can cause the loss of user files and/or data. See the DIRTY LOGS section for more information.

-l logdev

Specifies the device special file where the filesystem's external log resides. Only for those filesystems which use an external log. See the mkfs.xfs -l option, and refer to xfs(5) for a detailed description of the XFS log.

-r rtdev

Specifies the device special file where the filesystem's realtime section resides. Only for those filesystems which use a realtime section. See the mkfs.xfs -r option, and refer to xfs(5) for a detailed description of the XFS realtime section.

-n

No modify mode. Specifies that xfs_repair should not modify the filesystem but should only scan the filesystem and indicate what repairs would have been made. This option cannot be used together with -e.

-P

Disable prefetching of inode and directory blocks. Use this option if you find xfs_repair gets stuck and stops proceeding. Interrupting a stuck xfs_repair is safe.

-m maxmem

Specifies the approximate maximum amount of memory, in megabytes, to use for xfs_repair. xfs_repair has its own internal block cache which will scale out up to the lesser of the process's virtual address limit or about 75% of the system's physical RAM. This option overrides these limits.

NOTE: These memory limits are only approximate and may use more than the specified limit.

-c subopt=value

Change filesystem parameters. Refer to xfs_admin(8) for information on changing filesystem parameters.

-o subopt[=value]

Override what the program might conclude about the filesystem if left to its own devices.

The suboptions supported are:

bhash=bhashsize

overrides the default buffer cache hash size. The total number of buffer cache entries are limited to 8 times this amount. The default size is set to use up the remainder of 75% of the system's physical RAM size.

ag_stride=ags_per_concat_unit

This creates additional processing threads to parallel process AGs that span multiple concat units. This can significantly reduce repair times on concat based filesystems.

force_geometry

Check the filesystem even if geometry information could not be validated. Geometry information can not be validated if only a single allocation group exists and thus we do not have a backup superblock available, or if there are two allocation groups and the two superblocks do not agree on the filesystem geometry. Only use this option if you validated the geometry yourself and know what you are doing. If In doubt run in no modify mode first.

noquota

Don't validate quota counters at all. Quotacheck will be run during the next mount to recalculate all values.

-t interval

Modify reporting interval, specified in seconds. During long runs xfs_repair outputs its progress every 15 minutes. Reporting is only activated when ag_stride is enabled.

-v

Verbose output. May be specified multiple times to increase verbosity.

-d

Repair dangerously. Allow xfs_repair to repair an XFS filesystem mounted read only. This is typically done on a root filesystem from single user mode, immediately followed by a reboot.

-e

If any metadata corruption was repaired, the status returned is 4 instead of the usual 0. This option cannot be used together with -n.

-V

Prints the version number and exits.

### Checks Performed
The correctness of the crc32c checksum implementation will be tested before examining the filesystem. If the test fails, the program will abort.

Inconsistencies corrected include the following:

1.

Inode and inode blockmap (addressing) checks: bad magic number in inode, bad magic numbers in inode blockmap blocks, extents out of order, incorrect number of records in inode blockmap blocks, blocks claimed that are not in a legal data area of the filesystem, blocks that are claimed by more than one inode.

2.

Inode allocation map checks: bad magic number in inode map blocks, inode state as indicated by map (free or in-use) inconsistent with state indicated by the inode, inodes referenced by the filesystem that do not appear in the inode allocation map, inode allocation map referencing blocks that do not appear to contain inodes.

3.

Size checks: number of blocks claimed by inode inconsistent with inode size, directory size not block aligned, inode size not consistent with inode format.

4.

Directory checks: bad magic numbers in directory blocks, incorrect number of entries in a directory block, bad freespace information in a directory leaf block, entry pointing to an unallocated (free) or out of range inode, overlapping entries, missing or incorrect dot and dotdot entries, entries out of hashvalue order, incorrect internal directory pointers, directory type not consistent with inode format and size.

5.

Pathname checks: files or directories not referenced by a pathname starting from the filesystem root, illegal pathname components.

6.

Link count checks: link counts that do not agree with the number of directory references to the inode.

7.

Freemap checks: blocks claimed free by the freemap but also claimed by an inode, blocks unclaimed by any inode but not appearing in the freemap.

8.

Super Block checks: total free block and/or free i-node count incorrect, filesystem geometry inconsistent, secondary and primary superblocks contradictory.

Orphaned files and directories (allocated, in-use but unreferenced) are reconnected by placing them in the lost+found directory. The name assigned is the inode number.

### Disk Errors
xfs_repair aborts on most disk I/O errors. Therefore, if you are trying to repair a filesystem that was damaged due to a disk drive failure, steps should be taken to ensure that all blocks in the filesystem are readable and writable before attempting to use xfs_repair to repair the filesystem. A possible method is using dd(8) to copy the data onto a good disk.

### lost+found
The directory lost+found does not have to already exist in the filesystem being repaired. If the directory does not exist, it is automatically created if required. If it already exists, it will be checked for consistency and if valid will be used for additional orphaned files. Invalid lost+found directories are removed and recreated. Existing files in a valid lost+found are not removed or renamed.

### Corrupted Superblocks
XFS has both primary and secondary superblocks. xfs_repair uses information in the primary superblock to automatically find and validate the primary superblock against the secondary superblocks before proceeding. Should the primary be too corrupted to be useful in locating the secondary superblocks, the program scans the filesystem until it finds and validates some secondary superblocks. At that point, it generates a primary superblock.

### Quotas
If quotas are in use, it is possible that xfs_repair will clear some or all of the filesystem quota information. If so, the program issues a warning just before it terminates. If all quota information is lost, quotas are disabled and the program issues a warning to that effect.

Note that xfs_repair does not check the validity of quota limits. It is recommended that you check the quota limit information manually after xfs_repair. Also, space usage information is automatically regenerated the next time the filesystem is mounted with quotas turned on, so the next quota mount of the filesystem may take some time.

## DIAGNOSTICS
xfs_repair issues informative messages as it proceeds indicating what it has found that is abnormal or any corrective action that it has taken. Most of the messages are completely understandable only to those who are knowledgeable about the structure of the filesystem. Some of the more common messages are explained here. Note that the language of the messages is slightly different if xfs_repair is run in no-modify mode because the program is not changing anything on disk. No-modify mode indicates what it would do to repair the filesystem if run without the no-modify flag.

disconnected inode ino, moving to lost+found

An inode numbered ino was not connected to the filesystem directory tree and was reconnected to the lost+found directory. The inode is assigned the name of its inode number (ino). If a lost+found directory does not exist, it is automatically created.

disconnected dir inode ino, moving to lost+found

As above only the inode is a directory inode. If a directory inode is attached to lost+found, all of its children (if any) stay attached to the directory and therefore get automatically reconnected when the directory is reconnected.

imap claims in-use inode ino is free, correcting imap

The inode allocation map thinks that inode ino is free whereas examination of the inode indicates that the inode may be in use (although it may be disconnected). The program updates the inode allocation map.

imap claims free inode ino is in use, correcting imap

The inode allocation map thinks that inode ino is in use whereas examination of the inode indicates that the inode is not in use and therefore is free. The program updates the inode allocation map.

resetting inode ino nlinks from x to y

The program detected a mismatch between the number of valid directory entries referencing inode ino and the number of references recorded in the inode and corrected the the number in the inode.

fork-type fork in ino ino claims used block bno

Inode ino claims a block bno that is used (claimed) by either another inode or the filesystem itself for metadata storage. The fork-type is either data or attr indicating whether the problem lies in the portion of the inode that tracks regular data or the portion of the inode that stores XFS attributes. If the inode is a real-time (rt) inode, the message says so. Any inode that claims blocks used by the filesystem is deleted. If two or more inodes claim the same block, they are both deleted.

fork-type fork in ino ino claims dup extent ...

Inode ino claims a block in an extent known to be claimed more than once. The offset in the inode, start and length of the extent is given. The message is slightly different if the inode is a real-time (rt) inode and the extent is therefore a real-time (rt) extent.

inode ino - bad extent ...

An extent record in the blockmap of inode ino claims blocks that are out of the legal range of the filesystem. The message supplies the start, end, and file offset of the extent. The message is slightly different if the extent is a real-time (rt) extent.

bad fork-type fork in inode ino

There was something structurally wrong or inconsistent with the data structures that map offsets to filesystem blocks.

cleared inode ino

There was something wrong with the inode that was uncorrectable so the program freed the inode. This usually happens because the inode claims blocks that are used by something else or the inode itself is badly corrupted. Typically, this message is preceded by one or more messages indicating why the inode needed to be cleared.

bad attribute fork in inode ino, clearing attr fork

There was something wrong with the portion of the inode that stores XFS attributes (the attribute fork) so the program reset the attribute fork. As a result of this, all attributes on that inode are lost.

correcting nextents for inode ino, was x - counted y

The program found that the number of extents used to store the data in the inode is wrong and corrected the number. The message refers to nextents if the count is wrong on the number of extents used to store attribute information.

entry name in dir dir_ino not consistent with .. value (xxxx) in dir ino ino, junking entry name in directory inode dir_ino

The entry name in directory inode dir_ino references a directory inode ino. However, the .. entry in directory ino does not point back to directory dir_ino, so the program deletes the entry name in directory inode dir_ino. If the directory inode ino winds up becoming a disconnected inode as a result of this, it is moved to lost+found later.

entry name in dir dir_ino references already connected dir ino ino, junking entry name in directory inode dir_ino

The entry name in directory inode dir_ino points to a directory inode ino that is known to be a child of another directory. Therefore, the entry is invalid and is deleted. This message refers to an entry in a small directory. If this were a large directory, the last phrase would read "will clear entry".

entry references free inode ino in directory dir_ino, will clear entry

An entry in directory inode dir_ino references an inode ino that is known to be free. The entry is therefore invalid and is deleted. This message refers to a large directory. If the directory were small, the message would read "junking entry ...".

## EXIT STATUS
xfs_repair -n (no modify mode) will return a status of 1 if filesystem corruption was detected and 0 if no filesystem corruption was detected. xfs_repair run without the -n option will always return a status code of 0 if it completes without problems, unless the flag -e is used. If it is used, then status 4 is reported when any issue with the filesystem was found, but could be fixed. If a runtime error is encountered during operation, it will return a status of 1. In this case, xfs_repair should be restarted. If xfs_repair is unable to proceed due to a dirty log, it will return a status of 2. See below.

## DIRTY LOGS
Due to the design of the XFS log, a dirty log can only be replayed by the kernel, on a machine having the same CPU architecture as the machine which was writing to the log. xfs_repair cannot replay a dirty log and will exit with a status code of 2 when it detects a dirty log.

In this situation, the log can be replayed by mounting and immediately unmounting the filesystem on the same class of machine that crashed. Please make sure that the machine's hardware is reliable before replaying to avoid compounding the problems.

If mounting fails, the log can be erased by running xfs_repair with the -L option. All metadata updates in progress at the time of the crash will be lost, which may cause significant filesystem damage. This should only be used as a last resort.

## BUGS
The filesystem to be checked and repaired must have been unmounted cleanly using normal system administration procedures (the umount(8) command or system shutdown), not as a result of a crash or system reset. If the filesystem has not been unmounted cleanly, mount it and unmount it cleanly before running xfs_repair.

xfs_repair does not do a thorough job on XFS extended attributes. The structure of the attribute fork will be consistent, but only the contents of attribute forks that will fit into an inode are checked. This limitation will be fixed in the future.

The no-modify mode (-n option) is not completely accurate. It does not catch inconsistencies in the freespace and inode maps, particularly lost blocks or subtly corrupted maps (trees).

The no-modify mode can generate repeated warnings about the same problems because it cannot fix the problems as they are encountered.

If a filesystem fails to be repaired, a metadump image can be generated with xfs_metadump(8) and be sent to an XFS maintainer to be analysed and xfs_repair fixed and/or improved.

## SEE ALSO
dd(1), mkfs.xfs(8), umount(8), xfs_admin(8), xfs_metadump(8), xfs(5).


title: xfs_rtcp(8)

summary: XFS realtime copy command

text:
# xfs_rtcp(8)

## NAME
xfs_rtcp - XFS realtime copy command

## SYNOPSIS
xfs_rtcp [ -e extsize ] [ -p ] source ... target

xfs_rtcp -V

## DESCRIPTION
xfs_rtcp copies a file to the realtime partition on an XFS filesystem. If there is more than one source and target, the final argument (the target) must be a directory which already exists.

## OPTIONS
-e extsize

Sets the extent size of the destination realtime file.

-p

Use if the size of the source file is not an even multiple of the block size of the destination filesystem. When -p is specified xfs_rtcp will pad the destination file to a size which is an even multiple of the filesystem block size. This is necessary since the realtime file is created using direct I/O and the minimum I/O is the filesystem block size.

-V

Prints the version number and exits.

## SEE ALSO
xfs(5), mkfs.xfs(8), mount(8).

## CAVEATS
Currently, realtime partitions are not supported under the Linux version of XFS, and use of a realtime partition WILL CAUSE CORRUPTION on the data partition. As such, this command is made available for curious DEVELOPERS ONLY at this point in time.


title: xfs_scrub(8)

text:
# xfs_scrub(8)

## NAME
xfs_scrub - check and repair the contents of a mounted XFS filesystem

## SYNOPSIS
xfs_scrub [ -abCeMmnpTvx ] mount-point

xfs_scrub -V

## DESCRIPTION
xfs_scrub attempts to check and repair all metadata in a mounted XFS filesystem.

xfs_scrub asks the kernel to scrub all metadata objects in the filesystem. Metadata records are scanned for obviously bad values and then cross-referenced against other metadata. The goal is to establish a reasonable confidence about the consistency of the overall filesystem by examining the consistency of individual metadata records against the other metadata in the filesystem. Damaged metadata can be rebuilt from other metadata if there exists redundant data structures which are intact.

Filesystem corruption and optimization opportunities will be logged to the standard error stream. Enabling verbose mode will increase the amount of status information sent to the output.

If the kernel scrub reports that metadata needs repairs or optimizations and the user does not pass -n on the command line, this program will ask the kernel to make the repairs and to perform the optimizations. See the sections about optimizations and repairs for a list of optimizations and repairs known to this program. The kernel may not support repairing or optimizing the filesystem. If this is the case, the filesystem must be unmounted and xfs_repair(8) run on the filesystem to fix the problems.

## OPTIONS
-a errors

Abort if more than this many errors are found on the filesystem.

-b

Run in background mode. If the option is specified once, only run a single scrubbing thread at a time. If given more than once, an artificial delay of 100us is added to each scrub call to reduce CPU overhead even further.

-C fd

This option causes xfs_scrub to write progress information to the specified file description so that the progress of the filesystem check can be monitored. If the file description is a tty, a fancy progress bar is rendered. Otherwise, a simple numeric status dump compatible with the fsck -C format is output.

-e

Specifies what happens when errors are detected. If shutdown is given, the filesystem will be taken offline if errors are found. If continue is given, no action is taken if errors are found; this is the default behavior.

-k

Do not call TRIM on the free space.

-M real-mount-point

Open the this path for issuing scrub system calls to the kernel. The positional mount-point parameter will be used for displaying informational messages and logging. This parameter exists to enable process sandboxing for service mode.

-m file

Search this file for mounted filesystems instead of /etc/mtab.

-n

Only check filesystem metadata. Do not repair or optimize anything.

-o subopt[=value] Override what the program might conclude about the filesystem if left to its own devices.

The suboptions supported are:

autofsck

Decide the operating mode from the value of the autofsck filesystem property. See the filesystem properties section for more details.

fstrim_pct=percentage

To constrain the amount of time spent on fstrim activities during phase 8, this program tries to balance estimated runtime against completeness of the trim. In short, the program avoids small trim requests to save time. During phase 7, a log-scale histogram of free space extents is constructed. At the start of phase 8, a CDF is computed in decreasing order of extent length from the histogram buckets. A point corresponding to the fstrim percentage target is chosen from the CDF and mapped back to a histogram bucket. Free space extents at least as long as the bucket size are trimmed. Smaller extents are ignored.

By default, the percentage threshold is 99%.

iwarn

Treat informational messages as warnings. This will result in a nonzero return code, and a higher logging level.

-p

Only optimize filesystem metadata. If repairs are required, report them and exit.

-T

Print timing and memory usage information for each phase.

-v

Enable verbose mode, which prints periodic status updates.

-V

Prints the version number and exits.

-x

Read all file data extents to look for disk errors. xfs_scrub will issue O_DIRECT reads to the block device directly. If the block device is a SCSI disk, it will instead issue READ VERIFY commands directly to the disk. If media errors are found, the error report will include the disk offset, in bytes. If the media errors affect a file, the report will also include the inode number and file offset, in bytes. These actions will confirm that all file data blocks can be read from storage.

## OPTIMIZATIONS
Optimizations supported by this program include, but are not limited to:

•

Instructing the underlying storage to discard unused extents via the TRIM ioctl.

•

Updating secondary superblocks to match the primary superblock.

•

Turning off shared block write checks for files that no longer share blocks.

## REPAIRS
Repairs are performed by calling into the kernel. This limits the scope of repair activities to rebuilding primary data structures from secondary data structures, or secondary structures from primary structures. The existence of secondary data structures may require features that can only be turned on from mkfs.xfs(8). If errors cannot be repaired, the filesystem must be unmounted and xfs_repair(8) run. Repairs supported by the kernel include, but are not limited to:

•

Reconstructing extent allocation data.

•

Rebuilding free space information.

•

Rebuilding inode indexes.

•

Fixing minor corruptions of inode records.

•

Recalculating reference count information.

•

Reconstructing reverse mapping data from primary extent allocation data.

•

Scheduling a quotacheck for the next mount.

If corrupt metadata is successfully repaired, this program will log that a repair has succeeded instead of a corruption report.

## FILESYSTEM PROPERTIES
System administrators can convey their preferences for scrubbing of a particular filesystem by setting the filesystem property autofsck via the xfs_property(8) command on the filesystem. These preferences will be honored if the -o autofsck option is specified.

Recognized values for the autofsck property are:

none

Do not scan the filesystem at all.

check

Scan and report corruption and opportunities for optimization, but do not change anything.

optimize

Scan the filesystem and optimize where possible. Report corruptions, but do not fix them.

repair

Scan the filesystem, fix corruptions, and optimize where possible.

If the property is not set, the default is check if the filesystem has either reverse mapping btrees or parent pointers enabled, or none otherwise.

## EXIT CODE
The exit code returned by xfs_scrub is the sum of the following conditions:

0 - No errors

1 - File system errors left uncorrected

2 - File system optimizations possible

4 - Operational error

8 - Usage or syntax error

## CAVEATS
xfs_scrub is an immature utility! Do not run this program unless you have backups of your data! This program takes advantage of in-kernel scrubbing to verify a given data structure with locks held and can keep the filesystem busy for a long time. The kernel must be new enough to support the SCRUB_METADATA ioctl.

If errors are found and cannot be repaired, the filesystem must be unmounted and repaired.

## SEE ALSO
xfs_repair(8).