xfs - layout of the XFS filesystem
DESCRIPTION
An XFS filesystem can reside on a regular disk partition
or on a logical volume. An XFS filesystem has up to three
parts: a data section, a log section, and a realtime sec
tion. Using the default mkfs.xfs(8) options, the realtime
section is absent, and the log area is contained within
the data section. The log section can be either separate
from the data section or contained within it. The
filesystem sections are divided into a certain number of
blocks, whose size is specified at mkfs.xfs time with the
-b option.
The data section contains all the filesystem metadata
(inodes, directories, indirect blocks) as well as the user
file data for ordinary (non-realtime) files and the log
area if the log is internal to the data section. The data
section is divided into a number of allocation groups.
The number and size of the allocation groups are chosen by
mkfs.xfs so that there is normally a small number of
equal-sized groups. The number of allocation groups con
trols the amount of parallelism available in file and
block allocation. It should be increased from the default
if there is sufficient memory and a lot of allocation
activity. The number of allocation groups should not be
set very high, since this can cause large amounts of CPU
time to be used by the filesystem, especially when the
filesystem is nearly full. More allocation groups are
added (of the original size) when xfs_growfs(8) is run.
The log section (or area, if it is internal to the data
section) is used to store changes to filesystem metadata
while the filesystem is running until those changes are
made to the data section. It is written sequentially dur
ing normal operation and read only during mount. When
mounting a filesystem after a crash, the log is read to
complete operations that were in progress at the time of
the crash.
The realtime section is used to store the data of realtime
files. These files had an attribute bit set through
ioctl(2) after file creation, before any data was written
to the file. The realtime section is divided into a num
ber of extents of fixed size (specified at mkfs.xfs time).
Each file in the realtime section has an extent size that
is a multiple of the realtime section extent size.
Each allocation group contains several data structures.
The first sector contains the superblock. For allocation
groups after the first, the superblock is just a copy and
is not updated after mkfs.xfs. The next three sectors
contain information for block and inode allocation within
tion group are data structures to locate free blocks and
inodes; these are located through the header structures.
Each XFS filesystem is labeled with a Universal Unique
Identifier (UUID). The UUID is stored in every allocation
group header and is used to help distinguish one XFS
filesystem from another, therefore you should avoid using
dd or other block-by-block copying programs to copy XFS
filesystems. If two XFS filesystems on the same machine
have the same UUID, xfsdump(8) may become confused when
doing incremental and resumed dumps. xfsdump and xfsre
store are recommended for making copies of XFS filesys
tems.
OPERATIONS
Some functionality specific to the XFS filesystem is
accessible to applications through the Linux ioctl(2)
interface. These operations can be divided into two sec
tions - operations that operate on individual files, and
operations that operate on the filesystem itself. Care
should be taken when issuing these XFS ioctl calls to
ensure the target file descriptor does indeed represent a
file from an XFS filesystem. The fstatfs(2) system call
can be used to determine whether or not an arbitrary file
descriptor belongs to an XFS filesystem.
FILE OPERATIONS
In order to effect an operation on an individual file, the
descriptor argument passed to ioctl identifies the file
being operated on. The third argument described below
refers to the third argument of the ioctl system call
(which is traditionally a char * or void *). All of the
data structures and macros mentioned below are defined in
the <xfs/xfs_fs.h> header file.
XFS_IOC_FREESP
XFS_IOC_FREESP64
XFS_IOC_ALLOCSP
XFS_IOC_ALLOCSP64
Alter storage space associated with a section of
the ordinary file fildes. The section is specified
by a variable of type xfs_flock64_t, pointed to by
the third argument. The data type xfs_flock64_t
contains the following members: l_whence is 0, 1,
or 2 to indicate that the relative offset l_start
will be measured from the start of the file, the
current position, or the end of the file, respec
tively. l_start is the offset from the position
specified in l_whence. l_len is the size of the
section. An l_len value of zero frees up to the
end of the file; in this case, the end of file
(i.e., file size) is set to the beginning of the
this section is no longer accessible. If the sec
tion specified is beyond the current end of file,
the file is grown and filled with zeroes. The
l_len field is currently ignored, and should be set
to zero.
XFS_IOC_FREESP and XFS_IOC_FREESP64 are identical,
as are the XFS_IOC_ALLOCSP and XFS_IOC_ALLOCSP64
operations.
XFS_IOC_FSSETDM
Set the di_dmevmask and di_dmstate fields in an XFS
on-disk inode. The only legitimate values for
these fields are those previously returned in the
bs_dmevmask and bs_dmstate fields of the bulkstat
structure. The data referred to by the third argu
ment is a struct fsdmidata. This structure's mem
bers are fsd_dmevmask and fsd_dmstate. The
di_dmevmask field is set to the value in fsd_dmev
mask. The di_dmstate field is set to the value in
fsd_dmstate. This command is restricted to root or
to processes with device management capabilities.
Its sole purpose is to allow backup and restore
programs to restore the aforementioned critical on-
disk inode fields.
XFS_IOC_DIOINFO
Get information required to perform direct I/O on
the specified file descriptor. Direct I/O is per
formed directly to and from a user's data buffer.
Since the kernel's buffer cache is no longer
between the two, the user's data buffer must con
form to the same type of constraints as required
for accessing a raw disk partition. The third
argument points to a variable of type struct
dioattr, which contains the following members:
d_mem is the memory alignment requirement of the
user's data buffer. d_miniosz specifies block
size, minimum I/O request size, and I/O alignment.
The size of all I/O requests must be a multiple of
this amount and the value of the seek pointer at
the time of the I/O request must also be an integer
multiple of this amount. d_maxiosz is the maximum
I/O request size which can be performed on the file
descriptor. If an I/O request does not meet these
constraints, the read(2) or write(2) will fail with
EINVAL. All I/O requests are kept consistent with
any data brought into the cache with an access
through a non-direct I/O file descriptor.
XFS_IOC_FSGETXATTR
Get extended attributes associated with files in
XFS file systems. The third argument points to a
include: fsx_xflags (extended flag bits), fsx_ext
size (nominal extent size in file system blocks),
fsx_nextents (number of data extents in the file),
fsx_uuid (file unique id). Currently the only
meaningful bits for the fsx_xflags field are bit 0
(value 1), which if set means the file is a real
time file, and bit 1 (value 2), which if set means
the file has preallocated space. A fsx_extsize
value returned indicates that a preferred extent
size was previously set on the file, a fsx_extsize
of zero indicates that the defaults for that
filesystem will be used.
XFS_IOC_FSGETXATTRA
Identical to XFS_IOC_FSGETXATTR except that the
fsx_nextents field contains the number of attribute
extents in the file.
XFS_IOC_FSSETXATTR
Set extended attributes associated with files in
XFS file systems. The third argument points to a
variable of type struct fsxattr, but only the fol
lowing fields are used in this call: fsx_xflags and
fsx_extsize. The fsx_xflags realtime file bit, and
the file's extent size, may be changed only when
the file is empty.
XFS_IOC_GETBMAP
Get the block map for a segment of a file in an XFS
file system. The third argument points to an arry
of variables of type struct getbmap. All sizes and
offsets in the structure are in units of 512 bytes.
The structure fields include: bmv_offset (file off
set of segment), bmv_block (starting block of seg
ment), bmv_length (length of segment), bmv_count
(number of array entries, including the first), and
bmv_entries (number of entries filled in). The
first structure in the array is a header, and the
remaining structures in the array contain block map
information on return. The header controls itera
tive calls to the XFS_IOC_GETBMAP command. The
caller fills in the bmv_offset and bmv_length
fields of the header to indicate the area of inter
est in the file, and fills in the bmv_count field
to indicate the length of the array. If the
bmv_length value is set to -1 then the length of
the interesting area is the rest of the file. On
return from a call, the header is updated so that
the command can be reused to obtain more informa
tion, without re-initializing the structures. Also
on return, the bmv_entries field of the header is
set to the number of array entries actually filled
in. The non-header structures will be filled in
region of the file has no blocks (is a hole in the
file) then the bmv_block field is set to -1.
XFS_IOC_GETBMAPA
Identical to XFS_IOC_GETBMAP except that informa
tion about the attribute fork of the file is
returned.
XFS_IOC_RESVSP
XFS_IOC_RESVSP64
This command is used to allocate space to a file.
A range of bytes is specified using a pointer to a
variable of type xfs_flock64_t in the third argu
ment. The blocks are allocated, but not zeroed,
and the file size does not change. If the XFS
filesystem is configured to flag unwritten file
extents, performance will be negatively affected
when writing to preallocated space, since extra
filesystem transactions are required to convert
extent flags on the range of the file written. If
xfs_admin(8) reports unwritten=1, then the filesys
tem was made to flag unwritten extents.
XFS_IOC_UNRESVSP
XFS_IOC_UNRESVSP64
This command is used to free space from a file. A
range of bytes is specified using a pointer to a
variable of type xfs_flock64_t in the third argu
ment. Partial filesystem blocks are zeroed, and
whole filesystem blocks are removed from the file.
The file size does not change.
XFS_IOC_GETBIOSIZE
This command gets information about the preferred
buffered I/O size used by the system when perform
ing buffered I/O (e.g. standard Unix non-direct
I/O) to and from the file. The information is
passed back in a structure of type struct biosize
pointed to by the third argument. biosize lengths
are expressed in log base 2. That is if the value
is 14, then the true size is 2^14 (2 raised to the
14th power). The biosz_read field will contain the
current value used by the system when reading from
the file. Except at the end-of-file, the system
will read from the file in multiples of this
length. The biosz_write field will contain the
current value used by the system when writing to
the file. Except at the end-of-file, the system
will write to the file in multiples of this length.
The dfl_biosz_read and dfl_biosz_write will be set
to the system default values for the opened file.
The biosz_flags field will be set to 1 if the cur
rent read or write value has been explicitly set.
This command the preferred buffered I/O size used
by the system when performing buffered I/O (e.g.
standard Unix non-direct I/O) to and from the file.
The information is passed in a structure of type
struct biosize pointed to by the third argument.
Using smaller preferred I/O sizes can result in
performance improvements if the file is typically
accessed using small synchronous I/Os or if only a
small amount of the file is accessed using small
random I/Os, resulting in little or no use of the
additional data read in near the random I/Os.
To explicitly set the the preferred I/O sizes, the
biosz_flags field should be set to zero and the
biosz_read and biosz_write fields should be set to
the log base 2 of the desired read and write
lengths, respectively (e.g. 13 for 8K bytes, 14 for
16K bytes, 15 for 32K bytes, etc.). Valid values
are 13-16 inclusive for machines with a 4K byte
pagesize and 14-16 for machines with a 16K byte
pagesize. The specified read and write values must
also result in lengths that are greater than or
equal to the filesystem block size. The
dfl_biosz_read and dfl_biosz_write fields are
ignored.
If biosizes have already been explicitly set due to
a prior use of XFS_IOC_SETBIOSIZE, and the
requested sizes are larger then the existing sizes,
the ioctl call will return successfully and the
system will use the smaller of the two sizes. How
ever, if biosz_flags is set to 1, the system will
use the new values regardless of whether the new
sizes are larger or smaller than the old.
To reset the biosize values to the defaults for the
filesystem that the file resides in, the
biosz_flags field should be set to 2. The remain
der of the fields will be ignored in that case.
Changes made by XFS_IOC_SETBIOSIZE are transient.
The sizes are reset to the default values once the
reference count on the file drops to zero (e.g. all
open file descriptors to that file have been
closed). See mount(8) for details on how to set
the default biosize values for a filesystem.
XFS_IOC_PATH_TO_HANDLE
XFS_IOC_PATH_TO_FSHANDLE
XFS_IOC_FD_TO_HANDLE
XFS_IOC_OPEN_BY_HANDLE
XFS_IOC_READLINK_BY_HANDLE
XFS_IOC_ATTR_LIST_BY_HANDLE
XFS_IOC_FSSETDM_BY_HANDLE
These are all interfaces that are used to implement
various libhandle functions (see fd_to_handle(3)).
They are all subject to change and should not be
called directly by applications.
FILESYSTEM OPERATIONS
In order to effect one of the following operations, the
file descriptor argument passed to ioctl can be any open
file in the XFS filesystem in question.
XFS_IOC_FSINUMBERS
This interface is used to extract a list of valid
inode numbers from an XFS filesystem. It is
intended to be called iteratively, to obtain the
entire set of inodes. The information is passed in
and out via a structure of type xfs_fsop_bulkreq_t
pointed to by the third argument. lastip is a
pointer to a variable containing the last inode
number returned, initially it should be zero.
icount is the size of the array of structures spec
ified by ubuffer. ubuffer is the address of an
array of structures, of type xfs_inogrp_t. This
structure has the following elements: xi_startino
(starting inode number), xi_alloccount (count of
bits set in xi_allocmask), and xi_allocmask (mask
of allocated inodes in this group). The bitmask is
64 bits long, and the least significant bit corre
sponds to inode xi_startino. Each bit is set if
the corresponding inode is in use. ocount is a
pointer to a count of returned values, filled in by
the call. An output ocount value of zero means
that the inode table has been exhausted.
XFS_IOC_FSBULKSTAT
This interface is used to extract inode information
(stat information) "in bulk" from a filesystem. It
is intended to be called iteratively, to obtain
information about the entire set of inodes in a
filesystem. The information is passed in and out
via a structure of type xfs_fsop_bulkreq_t pointed
to by the third argument. lastip is a pointer to a
variable containing the last inode number returned,
initially it should be zero. icount indicates the
size of the array of structures specified by
ubuffer. ubuffer is the address of an array of
structures of type xfs_bstat_t. Many of the ele
ments in the structure are the same as for the stat
structure. The structure has the following ele
ments: bs_ino (inode number), bs_mode (type and
mode), bs_nlink (number of links), bs_uid (user
id), bs_gid (group id), bs_rdev (device value),
bs_blksize (block size of the filesystem), bs_size
bs_mtime (modify time), bs_ctime (inode change
time), bs_blocks (number of blocks used by the
file), bs_xflags (extended flags), bs_extsize
(extent size), bs_extents (number of extents),
bs_gen (generation count), bs_projid (project id),
bs_dmevmask (DMIG event mask), bs_dmstate (DMIG
state information), and bs_aextents (attribute
extent count). ocount is a pointer to a count of
returned values, filled in by the call. An output
ocount value of zero means that the inode table has
been exhausted.
XFS_IOC_FSBULKSTAT_SINGLE
This interface is a variant of the XFS_IOC_FSBULK
STAT interface, used to obtain information about a
single inode. for an open file in the filesystem
of interest. The same structure is used to pass
information in and out of the kernel, except no
output count parameter is used (should be initial
ized to zero). An error is returned if the inode
number is invalid.
XFS_IOC_THAW
XFS_IOC_FREEZE
XFS_IOC_GET_RESBLKS
XFS_IOC_SET_RESBLKS
XFS_IOC_FSGROWFSDATA
XFS_IOC_FSGROWFSLOG
XFS_IOC_FSGROWFSRT
XFS_IOC_FSCOUNTS
These interfaces are used to implement various
filesystem internal operations on XFS filesystems.
For XFS_IOC_FSGEOMETRY (get filesystem mkfs time
information), the output structure is of type
xfs_fsop_geom_t. For XFS_FS_COUNTS (get filesystem
dynamic global information), the output structure
is of type xfs_fsop_counts_t. The remainder of
these operations will not be described further as
they are not of general use to applications.
MOUNT OPTIONS
Refer to the mount(8) manual entry for descriptions of the
individual XFS mount options.
SEE ALSO
ioctl(2), fstatfs(2), mount(8), mkfs.xfs(8), xfs_info(8),
xfs_admin(8), xfsdump(8), xfsrestore(8).
Man(1) output converted with
man2html