xfsctl man page on aLinux

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
aLinux logo
[printable version]

XFSCTL(3)							     XFSCTL(3)

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  rep‐
       resent  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	 plat‐
       form_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	 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 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 mea‐
	      sured 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 argu‐
	      ment 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 aforemen‐
	      tioned 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 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	file  system  blocks),
	      fsx_nextents (number of data extents in the file).   A  fsx_ext‐
	      size  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 capa‐
			bility 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 multi‐
			ples   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  directo‐
			ries 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 sys‐
	      tems.   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 off‐
	      set  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	 actu‐
	      ally  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, 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	 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_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 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 itera‐
	      tively, 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  fol‐
	      lowing  elements: xi_startino (starting inode number), xi_alloc‐
	      count (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 infor‐
	      mation)  "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 filesys‐
	      tem), 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 (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 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 inter‐
	      nal 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 applica‐
	      tions.

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

								     XFSCTL(3)
[top]

List of man pages available for aLinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net