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