Seth Woolley's Man Viewer

xfsctl(3) - xfsctl, xfsctl - control XFS filesystems and individual files - man 3 xfsctl

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

XFSCTL(3)                                                            XFSCTL(3)



NAME
       xfsctl - control XFS filesystems and individual files

C SYNOPSIS
       #include <xfs/libxfs.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(1,n) descriptor (both must be supplied) do indeed  rep-
       resent  a  file(1,n)  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(1,n) descriptor belong to an XFS filesystem.  These are not portable
       however,   so   the    routines    platform_test_xfs_fd    and    plat-
       form_test_xfs_path provide a platform-independent mechanism.


   FILE OPERATIONS
       In order to effect an operation on an individual file(1,n), the pathname and
       descriptor arguments passed to xfsctl identifies the file(1,n)  being  oper-
       ated  on.  The final argument described below refers to the final argu-
       ment of xfsctl.  All of the data structures and macros mentioned  below
       are defined in(1,8) 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(1,n) 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 mea-
              sured from the start of the file(1,n), the current position,  or  the
              end  of  the file(1,n), respectively.  l_start is the offset from the
              position specified in(1,8) l_whence.  l_len is the size of  the  sec-
              tion.   An  l_len value of zero frees up to the end of the file(1,n);
              in(1,8) this case, the end of file(1,n) (i.e., file(1,n) size) is  set(7,n,1 builtins)  to  the
              beginning  of  the  section  freed.  Any data previously written
              into this section is no longer accessible.  If the section spec-
              ified  is  beyond the current end of file(1,n), the file(1,n) is grown and
              filled with zeroes.  The l_len field is currently  ignored,  and
              should be set(7,n,1 builtins) 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(1,8)  an  XFS  on-disk
              inode.   The  only  legitimate values for these fields are those
              previously returned in(1,8) the bs_dmevmask and bs_dmstate fields  of
              the bulkstat structure.  The data referred to by the final argu-
              ment is  a  struct  fsdmidata.   This  structure's  members  are
              fsd_dmevmask  and  fsd_dmstate.  The di_dmevmask field is set(7,n,1 builtins) to
              the value in(1,8) fsd_dmevmask.  The di_dmstate field is set(7,n,1 builtins)  to  the
              value  in(1,8) 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 aforemen-
              tioned critical on-disk inode fields.

       XFS_IOC_DIOINFO
              Get information required to perform direct I/O on the  specified
              file(1,n) 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(3x,7,8,3x cbreak)
              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(1,2,n)  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(1,n) descriptor.  If an I/O request does not meet these
              constraints, the read(2,n,1 builtins)(2) or write(1,2)(2) will fail with EINVAL.  All
              I/O  requests are kept consistent with any data brought into the
              cache with an access(2,5) through a non-direct I/O file(1,n) descriptor.

       XFS_IOC_FSGETXATTR
              Get additional attributes associated with files in(1,8) XFS file(1,n) sys-
              tems.   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(1,8)  file(1,n)  system  blocks),
              fsx_nextents (number of data extents in(1,8) the file(1,n)).   A  fsx_ext-
              size  value  returned indicates that a preferred extent size was
              previously set(7,n,1 builtins) on the file(1,n), 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(1,n) is a realtime file.
              Bit 1 (0x2) - XFS_XFLAG_PREALLOC
                        The file(1,n) has preallocated space.
              Bit 3 (0x8) - XFS_XFLAG_IMMUTABLE
                        The file(1,n) is immutable - it cannot be modified, deleted
                        or renamed, no link(1,2) can be created to this file(1,n) and no
                        data can be written to the file.  Only  the  superuser
                        or  a process possessing the CAP_LINUX_IMMUTABLE capa-
                        bility can set(7,n,1 builtins) or clear(1,3x,3x clrtobot) this flag.
              Bit 4 (0x10) - XFS_XFLAG_APPEND
                        The file(1,n) is append-only -  it  can  only  be  open(2,3,n)  in(1,8)
                        append  mode  for  writing.   Only  the superuser or a
                        process possessing the CAP_LINUX_IMMUTABLE  capability
                        can set(7,n,1 builtins) or clear(1,3x,3x clrtobot) this flag.
              Bit 5 (0x20) - XFS_XFLAG_SYNC
                        All writes to the file(1,n) are synchronous.
              Bit 6 (0x40) - XFS_XFLAG_NOATIME
                        When  the  file(1,n)  is  accessed, its atime record is not
                        modified.
              Bit 7 (0x80) - XFS_XFLAG_NODUMP
                        The file(1,n) should be skipped by backup utilities.
              Bit 8 (0x100) - XFS_XFLAG_RTINHERIT
                        Realtime inheritance bit - new files  created  in(1,8)  the
                        directory  will  be  automatically  realtime,  and new
                        directories created in(1,8) the directory will inherit  the
                        inheritance bit.
              Bit 9 (0x200) - XFS_XFLAG_PROJINHERIT
                        Project  inheritance  bit  - new files and directories
                        created in(1,8) 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(7,n,1 builtins) on a directory and disallows  creation
                        of symbolic links in(1,8) that directory.
              Bit 31 (0x80000000) - XFS_XFLAG_HASATTR
                        The file(1,n) 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(1,8) the file.


       XFS_IOC_FSSETXATTR
              Set additional attributes associated with files in(1,8) XFS file(1,n) sys-
              tems.   The  final  argument points to a variable of type struct
              fsxattr, but only the following fields are used  in(1,8)  this  call:
              fsx_xflags  and  fsx_extsize.  The fsx_xflags realtime file(1,n) bit,
              and the file(1,n)'s extent size, may be changed only when the file(1,n) is
              empty.


       XFS_IOC_GETBMAP
              Get the block map for a segment of a file(1,n) in(1,8) an XFS file(1,n) system.
              The final argument points to an arry of variables of type struct
              getbmap.  All sizes and offsets in(1,8) the structure are in(1,8) units(1,7) of
              512 bytes.  The structure fields include: bmv_offset (file(1,n)  off-
              set(7,n,1 builtins)   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(1,8)).  The first  structure  in(1,8)  the  array  is  a
              header,  and the remaining structures in(1,8) the array contain block
              map information on return.  The header controls iterative  calls
              to  the  XFS_IOC_GETBMAP  command.   The  caller  fills  in(1,8)  the
              bmv_offset and bmv_length fields of the header to  indicate  the
              area  of  interest in(1,8) the file(1,n), and fills in(1,8) the bmv_count field
              to indicate the length of the array.  If the bmv_length value is
              set(7,n,1 builtins) 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(7,n,1 builtins) to the number of array entries actu-
              ally filled in.  The non-header structures  will  be  filled  in(1,8)
              with  bmv_offset, bmv_block, and bmv_length.  If a region of the
              file(1,n) has no blocks (is a hole in(1,8) the file(1,n))  then  the  bmv_block
              field is set(7,n,1 builtins) to -1.


       XFS_IOC_GETBMAPA
              Identical  to  XFS_IOC_GETBMAP except that information about the
              attribute fork of the file(1,n) 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(1,8) the final argument.  The blocks are  allocated,
              but  not  zeroed, and the file(1,n) size does not change.  If the XFS
              filesystem is configured to flag unwritten file(1,n) extents, perfor-
              mance  will  be negatively affected when writing to preallocated
              space, since extra filesystem transactions are required to  con-
              vert  extent  flags  on  the  range  of  the  file(1,n)  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(1,8) the final argument.  Partial filesystem blocks
              are zeroed, and whole filesystem blocks  are  removed  from  the
              file.  The file(1,n) size does not change.



       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 lib-
              handle 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(2,3,n) file(1,n) in(1,8)  the  XFS
       filesystem in(1,8) 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  itera-
              tively,  to obtain the entire set(7,n,1 builtins) of inodes.  The information is
              passed in(1,8) 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 fol-
              lowing elements: xi_startino (starting inode number),  xi_alloc-
              count  (count  of  bits  set(7,n,1 builtins)  in(1,8) xi_allocmask), and xi_allocmask
              (mask of allocated inodes in(1,8) this group).   The  bitmask  is  64
              bits  long,  and  the least significant bit corresponds to inode
              xi_startino.  Each bit is set(7,n,1 builtins) if(3,n) the corresponding inode  is  in(1,8)
              use.   ocount is a pointer to a count of returned values, filled
              in(1,8) 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(1,2) infor-
              mation) "in(1,8) bulk" from a  filesystem.   It  is  intended  to  be
              called  iteratively,  to obtain information about the entire set(7,n,1 builtins)
              of inodes in(1,8) a filesystem.  The information is passed in(1,8) 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(1,8) the structure are the
              same as for the stat(1,2) 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  filesys-
              tem),  bs_size  (file(1,n)  size  in(1,8)  bytes), bs_atime (access(2,5) time(1,2,n)),
              bs_mtime (modify time(1,2,n)), bs_ctime (inode change time(1,2,n)),  bs_blocks
              (number of blocks used by the file(1,n)), 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_aex-
              tents  (attribute extent count).  ocount is a pointer to a count
              of returned values, filled in(1,8) 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(2,3,n)
              file(1,n)  in(1,8) the filesystem of interest.  The same structure is used
              to pass information in(1,8) and out of the kernel, except  no  output
              count  parameter  is  used  (should be initialized to zero).  An
              error(8,n) is returned if(3,n) 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 inter-
              nal  operations on XFS filesystems.  For XFS_IOC_FSGEOMETRY (get
              filesystem mkfs time(1,2,n) 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  applica-
              tions.

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



                                                                     XFSCTL(3)

References for this manual (incoming links)