Provided by: xfslibs-dev_3.1.7_i386 bug

NAME

       xfsctl - control XFS filesystems and individual files

C SYNOPSIS

       #include <xfs/xfs.h>

       int xfsctl(const char *path, int fd, int cmd, void *ptr);

       int platform_test_xfs_fd(int fd);
       int platform_test_xfs_path(const char *path);

DESCRIPTION

       Some  functionality  specific  to  the  XFS filesystem is accessible to
       applications through platform-specific system call  interfaces.   These
       operations  can  be divided into two sections - operations that operate
       on individual files, and operations  that  operate  on  the  filesystem
       itself.  Care should be taken when issuing xfsctl() calls to ensure the
       target path and file descriptor  (both  must  be  supplied)  do  indeed
       represent  a file from an XFS filesystem.  The statfs(2) and fstatfs(2)
       system calls can be used to determine whether or not an arbitrary  path
       or file descriptor belong to an XFS filesystem.  These are not portable
       however,     so     the     routines     platform_test_xfs_fd()     and
       platform_test_xfs_path() provide a platform-independent mechanism.

   File Operations
       In order to effect an operation on an individual file, the pathname and
       descriptor  arguments  passed  to  xfsctl  identifies  the  file  being
       operated  on.   The  final argument described below refers to the final
       argument of xfsctl.  All of the data structures  and  macros  mentioned
       below are defined in the <xfs/xfs_fs.h> header file.

       XFS_IOC_ALLOCSP
       XFS_IOC_ALLOCSP64
       XFS_IOC_FREESP
       XFS_IOC_FREESP64
              Alter  storage  space  associated with a section of the ordinary
              file specified.  The section is specified by a variable of  type
              xfs_flock64_t,  pointed to by the final 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, respectively (i.e., l_start is the offset
              from  the  position  specified  in  l_whence).   If  the  offset
              specified is before the current end of file, any data previously
              written into this section  is  no  longer  accessible.   If  the
              offset  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_ALLOCSP,     XFS_IOC_ALLOCSP64,    XFS_IOC_FREESP    and
              XFS_IOC_FREESP64 operations are all identical.

       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 final
              argument is a struct fsdmidata.  This  structure's  members  are
              fsd_dmevmask  and  fsd_dmstate.  The di_dmevmask field is set to
              the value in fsd_dmevmask.  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 performed 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 conform to
              the same type of constraints as required  for  accessing  a  raw
              disk partition.  The final 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 additional attributes associated  with  files  in  XFS  file
              systems.  The final argument points to a variable of type struct
              fsxattr, whose fields include: fsx_xflags (extended flag  bits),
              fsx_extsize   (nominal  extent  size  in  file  system  blocks),
              fsx_nextents  (number  of  data  extents  in   the   file).    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.
              Currently the meaningful bits for the fsx_xflags field are:
              Bit 0 (0x1) - XFS_XFLAG_REALTIME
                        The file is a realtime file.
              Bit 1 (0x2) - XFS_XFLAG_PREALLOC
                        The file has preallocated space.
              Bit 3 (0x8) - XFS_XFLAG_IMMUTABLE
                        The file is immutable - it cannot be modified, deleted
                        or renamed, no link can be created to this file and no
                        data can be written to the file.  Only  the  superuser
                        or   a   process  possessing  the  CAP_LINUX_IMMUTABLE
                        capability can set or clear this flag.
              Bit 4 (0x10) - XFS_XFLAG_APPEND
                        The file is append-only -  it  can  only  be  open  in
                        append  mode  for  writing.   Only  the superuser or a
                        process possessing the CAP_LINUX_IMMUTABLE  capability
                        can set or clear this flag.
              Bit 5 (0x20) - XFS_XFLAG_SYNC
                        All writes to the file are synchronous.
              Bit 6 (0x40) - XFS_XFLAG_NOATIME
                        When  the  file  is  accessed, its atime record is not
                        modified.
              Bit 7 (0x80) - XFS_XFLAG_NODUMP
                        The file should be skipped by backup utilities.
              Bit 8 (0x100) - XFS_XFLAG_RTINHERIT
                        Realtime inheritance bit - new files  created  in  the
                        directory  will  be  automatically  realtime,  and new
                        directories created in the directory will inherit  the
                        inheritance bit.
              Bit 9 (0x200) - XFS_XFLAG_PROJINHERIT
                        Project  inheritance  bit  - new files and directories
                        created in the  directory  will  inherit  the  parents
                        project  ID.  New directories also inherit the project
                        inheritance bit.
              Bit 10 (0x400) - XFS_XFLAG_NOSYMLINKS
                        Can only be set on a directory and disallows  creation
                        of symbolic links in that directory.
              Bit 11 (0x800) - XFS_XFLAG_EXTSIZE
                        Extent  size bit - if a basic extent size value is set
                        on the  file  then  the  allocator  will  allocate  in
                        multiples   of   the  set  size  for  this  file  (see
                        XFS_IOC_FSSETXATTR below).
              Bit 12 (0x1000) - XFS_XFLAG_EXTSZINHERIT
                        Extent  size  inheritance  bit   -   new   files   and
                        directories  created in the directory will inherit the
                        parents    basic    extent     size     value     (see
                        XFS_IOC_FSSETXATTR  below).   Can  only  be  set  on a
                        directory.
              Bit 13 (0x2000) - XFS_XFLAG_NODEFRAG
                        No defragment file bit - the file  should  be  skipped
                        during  a defragmentation operation. When applied to a
                        directory, new  files  and  directories  created  will
                        inherit the no-defrag bit.
              Bit 14 (0x4000) - XFS_XFLAG_FILESTREAM
                        Filestream  allocator  bit  -  allows  a  directory to
                        reserve an allocation group for exclusive use by files
                        created  within that directory. Files being written in
                        other directories will not  use  the  same  allocation
                        group  and  so files within different directories will
                        not interleave extents on  disk.  The  reservation  is
                        only  active while files are being created and written
                        into the directory.
              Bit 31 (0x80000000) - XFS_XFLAG_HASATTR
                        The file has extended attributes associated with it.
       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  additional  attributes  associated  with  files in XFS file
              systems.  The final argument points to a variable of type struct
              fsxattr,  but  only  the following 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, except in the case of a directory where the  extent  size
              can be set at any time (this value is only used for regular file
              allocations, so should only be set on a directory in conjunction
              with the XFS_XFLAG_EXTSZINHERIT flag).

       XFS_IOC_GETBMAP
              Get the block map for a segment of a file in an XFS file system.
              The final 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
              offset  of  segment),  bmv_block  (starting  block  of segment),
              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 iterative  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  interest 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 information, 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
              with  bmv_offset, bmv_block, and bmv_length.  If a 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 information 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 final argument.  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_info(8)   reports   unwritten=1,   then   the
              filesystem 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 final argument.  Partial filesystem blocks
              are zeroed, and whole filesystem blocks  are  removed  from  the
              file.  The file size does not change.

       XFS_IOC_ZERO_RANGE
              This  command  is  used  to  convert  a range of a file to zeros
              without issuing data IO.  A range of bytes is specified using  a
              pointer  to  a  variable  of  type  xfs_flock64_t  in  the final
              argument.  Blocks are preallocated for regions that  span  holes
              in  the  file,  and  the  entire range is converted to unwritten
              extents.  This operation is a fast  method  of  overwriting  any
              from  the range specified with zeros without removing any blocks
              or having to write zeros to disk.  Any subsequent  read  in  the
              given  range  will return zeros until new data is written.  This
              functionality requires filesystems to support unwritten extents.
              If xfs_info(8) reports unwritten=1, then the filesystem was made
              to flag unwritten extents.

       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_ATTR_MULTI_BY_HANDLE
       XFS_IOC_FSSETDM_BY_HANDLE
              These are all interfaces that  are  used  to  implement  various
              libhandle  functions  (see  open_by_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 pathname and
       descriptor arguments passed to xfsctl() 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 final 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 specified 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 corresponds 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
              final  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 elements in the structure are the
              same as for the stat structure.  The structure has the following
              elements:  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 (file  size  in  bytes),  bs_atime  (access
              time),  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_lo (project id
              -  low  word),  bs_projid_hi  (project id - high word, used when
              projid32bit feature is enabled), 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_FSBULKSTAT 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  initialized  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.

SEE ALSO

       fstatfs(2), statfs(2), xfs(5), xfs_info(8).

                                                                     XFSCTL(3)