1XFSCTL(3)                  Library Functions Manual                  XFSCTL(3)
2
3
4

NAME

6       xfsctl - control XFS filesystems and individual files
7

C SYNOPSIS

9       #include <xfs/xfs.h>
10
11       int xfsctl(const char *path, int fd, int cmd, void *ptr);
12
13       int platform_test_xfs_fd(int fd);
14       int platform_test_xfs_path(const char *path);
15

DESCRIPTION

17       Some  functionality  specific  to  the  XFS filesystem is accessible to
18       applications through platform-specific system call  interfaces.   These
19       operations  can  be divided into two sections - operations that operate
20       on individual files, and operations  that  operate  on  the  filesystem
21       itself.  Care should be taken when issuing xfsctl() calls to ensure the
22       target path and file descriptor (both must be supplied) do indeed  rep‐
23       resent  a  file  from  an XFS filesystem.  The statfs(2) and fstatfs(2)
24       system calls can be used to determine whether or not an arbitrary  path
25       or file descriptor belong to an XFS filesystem.  These are not portable
26       however,   so   the   routines   platform_test_xfs_fd()    and    plat‐
27       form_test_xfs_path() provide a platform-independent mechanism.
28
29   File Operations
30       In order to effect an operation on an individual file, the pathname and
31       descriptor arguments passed to xfsctl identifies the file  being  oper‐
32       ated  on.  The final argument described below refers to the final argu‐
33       ment of xfsctl.  All of the data structures and macros mentioned  below
34       are defined in the <xfs/xfs_fs.h> header file.
35
36       XFS_IOC_ALLOCSP
37       XFS_IOC_ALLOCSP64
38       XFS_IOC_FREESP
39       XFS_IOC_FREESP64
40              Alter  storage  space  associated with a section of the ordinary
41              file specified.  The section is specified by a variable of  type
42              xfs_flock64_t,  pointed to by the final argument.  The data type
43              xfs_flock64_t contains the following members: l_whence is 0,  1,
44              or  2  to indicate that the relative offset l_start will be mea‐
45              sured from the start of the file, the current position,  or  the
46              end  of the file, respectively (i.e., l_start is the offset from
47              the position specified in l_whence).  If the offset specified is
48              before the current end of file, any data previously written into
49              this section is no longer accessible.  If the  offset  specified
50              is  beyond the current end of file, the file is grown and filled
51              with zeroes.  The l_len field is currently ignored,  and  should
52              be set to zero.
53
54              XFS_IOC_ALLOCSP,     XFS_IOC_ALLOCSP64,    XFS_IOC_FREESP    and
55              XFS_IOC_FREESP64 operations are all identical.
56
57       XFS_IOC_FSSETDM
58              Set the di_dmevmask and di_dmstate  fields  in  an  XFS  on-disk
59              inode.   The  only  legitimate values for these fields are those
60              previously returned in the bs_dmevmask and bs_dmstate fields  of
61              the bulkstat structure.  The data referred to by the final argu‐
62              ment is  a  struct  fsdmidata.   This  structure's  members  are
63              fsd_dmevmask  and  fsd_dmstate.  The di_dmevmask field is set to
64              the value in fsd_dmevmask.  The di_dmstate field is set  to  the
65              value  in fsd_dmstate.  This command is restricted to root or to
66              processes with device management capabilities.  Its sole purpose
67              is to allow backup and restore programs to restore the aforemen‐
68              tioned critical on-disk inode fields.
69
70       XFS_IOC_DIOINFO
71              Get information required to perform direct I/O on the  specified
72              file descriptor.  Direct I/O is performed directly to and from a
73              user's data buffer.  Since  the  kernel's  buffer  cache  is  no
74              longer  between  the two, the user's data buffer must conform to
75              the same type of constraints as required  for  accessing  a  raw
76              disk partition.  The final argument points to a variable of type
77              struct dioattr, which contains the following members:  d_mem  is
78              the  memory  alignment  requirement  of  the user's data buffer.
79              d_miniosz specifies block size, minimum I/O  request  size,  and
80              I/O  alignment.  The size of all I/O requests must be a multiple
81              of this amount and the value of the seek pointer at the time  of
82              the I/O request must also be an integer multiple of this amount.
83              d_maxiosz is the maximum I/O request size which can be performed
84              on  the  file descriptor.  If an I/O request does not meet these
85              constraints, the read(2) or write(2) will fail with EINVAL.  All
86              I/O  requests are kept consistent with any data brought into the
87              cache with an access through a non-direct I/O file descriptor.
88
89       XFS_IOC_FSGETXATTR
90              Get additional attributes associated with files in XFS file sys‐
91              tems.   The  final  argument points to a variable of type struct
92              fsxattr, whose fields include: fsx_xflags (extended flag  bits),
93              fsx_extsize   (nominal  extent  size  in  file  system  blocks),
94              fsx_nextents (number of data extents in the file).   A  fsx_ext‐
95              size  value  returned indicates that a preferred extent size was
96              previously set on the file, a fsx_extsize of zero indicates that
97              the  defaults  for  that filesystem will be used.  Currently the
98              meaningful bits for the fsx_xflags field are:
99              Bit 0 (0x1) - XFS_XFLAG_REALTIME
100                        The file is a realtime file.
101              Bit 1 (0x2) - XFS_XFLAG_PREALLOC
102                        The file has preallocated space.
103              Bit 3 (0x8) - XFS_XFLAG_IMMUTABLE
104                        The file is immutable - it cannot be modified, deleted
105                        or renamed, no link can be created to this file and no
106                        data can be written to the file.  Only  the  superuser
107                        or  a process possessing the CAP_LINUX_IMMUTABLE capa‐
108                        bility can set or clear this flag.
109              Bit 4 (0x10) - XFS_XFLAG_APPEND
110                        The file is append-only -  it  can  only  be  open  in
111                        append  mode  for  writing.   Only  the superuser or a
112                        process possessing the CAP_LINUX_IMMUTABLE  capability
113                        can set or clear this flag.
114              Bit 5 (0x20) - XFS_XFLAG_SYNC
115                        All writes to the file are synchronous.
116              Bit 6 (0x40) - XFS_XFLAG_NOATIME
117                        When  the  file  is  accessed, its atime record is not
118                        modified.
119              Bit 7 (0x80) - XFS_XFLAG_NODUMP
120                        The file should be skipped by backup utilities.
121              Bit 8 (0x100) - XFS_XFLAG_RTINHERIT
122                        Realtime inheritance bit - new files  created  in  the
123                        directory  will  be  automatically  realtime,  and new
124                        directories created in the directory will inherit  the
125                        inheritance bit.
126              Bit 9 (0x200) - XFS_XFLAG_PROJINHERIT
127                        Project  inheritance  bit  - new files and directories
128                        created in the  directory  will  inherit  the  parents
129                        project  ID.  New directories also inherit the project
130                        inheritance bit.
131              Bit 10 (0x400) - XFS_XFLAG_NOSYMLINKS
132                        Can only be set on a directory and disallows  creation
133                        of symbolic links in that directory.
134              Bit 11 (0x800) - XFS_XFLAG_EXTSIZE
135                        Extent  size bit - if a basic extent size value is set
136                        on the file then the allocator will allocate in multi‐
137                        ples   of   the   set   size   for   this   file  (see
138                        XFS_IOC_FSSETXATTR below).
139              Bit 12 (0x1000) - XFS_XFLAG_EXTSZINHERIT
140                        Extent size inheritance bit - new files  and  directo‐
141                        ries created in the directory will inherit the parents
142                        basic  extent  size  value   (see   XFS_IOC_FSSETXATTR
143                        below).  Can only be set on a directory.
144              Bit 13 (0x2000) - XFS_XFLAG_NODEFRAG
145                        No  defragment  file  bit - the file should be skipped
146                        during a defragmentation operation. When applied to  a
147                        directory,  new  files  and  directories  created will
148                        inherit the no-defrag bit.
149              Bit 14 (0x4000) - XFS_XFLAG_FILESTREAM
150                        Filestream allocator  bit  -  allows  a  directory  to
151                        reserve an allocation group for exclusive use by files
152                        created within that directory. Files being written  in
153                        other  directories  will  not  use the same allocation
154                        group and so files within different  directories  will
155                        not  interleave  extents  on  disk. The reservation is
156                        only active while files are being created and  written
157                        into the directory.
158              Bit 31 (0x80000000) - XFS_XFLAG_HASATTR
159                        The file has extended attributes associated with it.
160       XFS_IOC_FSGETXATTRA
161              Identical  to  XFS_IOC_FSGETXATTR  except  that the fsx_nextents
162              field contains the number of attribute extents in the file.
163
164
165       XFS_IOC_FSSETXATTR
166              Set additional attributes associated with files in XFS file sys‐
167              tems.   The  final  argument points to a variable of type struct
168              fsxattr, but only the following fields are used  in  this  call:
169              fsx_xflags, fsx_extsize and fsx_projid.  The fsx_xflags realtime
170              file bit and the file's extent size may be changed only when the
171              file  is  empty,  except  in  the  case of a directory where the
172              extent size can be set at any time (this value is only used  for
173              regular  file  allocations, so should only be set on a directory
174              in conjunction with the XFS_XFLAG_EXTSZINHERIT flag).
175
176
177       XFS_IOC_GETBMAP
178              Get the block map for a segment of a file in an XFS file system.
179              The final argument points to an arry of variables of type struct
180              getbmap.  All sizes and offsets in the structure are in units of
181              512  bytes.  The structure fields include: bmv_offset (file off‐
182              set  of  segment),  bmv_block  (starting  block   of   segment),
183              bmv_length  (length  of  segment),  bmv_count  (number  of array
184              entries,  including  the  first),  and  bmv_entries  (number  of
185              entries  filled  in).   The  first  structure  in the array is a
186              header, and the remaining structures in the array contain  block
187              map  information on return.  The header controls iterative calls
188              to  the  XFS_IOC_GETBMAP  command.   The  caller  fills  in  the
189              bmv_offset  and  bmv_length fields of the header to indicate the
190              area of interest in the file, and fills in the  bmv_count  field
191              to indicate the length of the array.  If the bmv_length value is
192              set to -1 then the length of the interesting area is the rest of
193              the  file.  On return from a call, the header is updated so that
194              the command can be reused to obtain  more  information,  without
195              re-initializing the structures.  Also on return, the bmv_entries
196              field of the header is set to the number of array entries  actu‐
197              ally  filled  in.   The  non-header structures will be filled in
198              with bmv_offset, bmv_block, and bmv_length.  If a region of  the
199              file  has  no  blocks (is a hole in the file) then the bmv_block
200              field is set to -1.
201
202
203       XFS_IOC_GETBMAPA
204              Identical to XFS_IOC_GETBMAP except that information  about  the
205              attribute fork of the file is returned.
206
207
208       XFS_IOC_RESVSP
209
210       XFS_IOC_RESVSP64
211              This  command  is  used to allocate space to a file.  A range of
212              bytes is specified  using  a  pointer  to  a  variable  of  type
213              xfs_flock64_t  in the final argument.  The blocks are allocated,
214              but not zeroed, and the file size does not change.  If  the  XFS
215              filesystem is configured to flag unwritten file extents, perfor‐
216              mance will be negatively affected when writing  to  preallocated
217              space,  since extra filesystem transactions are required to con‐
218              vert extent  flags  on  the  range  of  the  file  written.   If
219              xfs_info(8) reports unwritten=1, then the filesystem was made to
220              flag unwritten extents.
221
222
223       XFS_IOC_UNRESVSP
224
225       XFS_IOC_UNRESVSP64
226              This command is used to free space from  a  file.   A  range  of
227              bytes  is  specified  using  a  pointer  to  a  variable of type
228              xfs_flock64_t in the final argument.  Partial filesystem  blocks
229              are  zeroed,  and  whole  filesystem blocks are removed from the
230              file.  The file size does not change.
231
232
233       XFS_IOC_ZERO_RANGE
234              This command is used to convert a range of a file to zeros with‐
235              out  issuing  data  IO.   A  range of bytes is specified using a
236              pointer to a variable of type xfs_flock64_t in the  final  argu‐
237              ment.   Blocks  are  preallocated for regions that span holes in
238              the file,  and  the  entire  range  is  converted  to  unwritten
239              extents.   This  operation  is  a fast method of overwriting any
240              from the range specified with zeros without removing any  blocks
241              or  having  to  write zeros to disk.  Any subsequent read in the
242              given range will return zeros until new data is  written.   This
243              functionality requires filesystems to support unwritten extents.
244              If xfs_info(8) reports unwritten=1, then the filesystem was made
245              to flag unwritten extents.
246
247
248
249       XFS_IOC_PATH_TO_HANDLE
250       XFS_IOC_PATH_TO_FSHANDLE
251       XFS_IOC_FD_TO_HANDLE
252       XFS_IOC_OPEN_BY_HANDLE
253       XFS_IOC_READLINK_BY_HANDLE
254       XFS_IOC_ATTR_LIST_BY_HANDLE
255       XFS_IOC_ATTR_MULTI_BY_HANDLE
256       XFS_IOC_FSSETDM_BY_HANDLE
257              These are all interfaces that are used to implement various lib‐
258              handle functions (see open_by_handle(3)).  They are all  subject
259              to change and should not be called directly by applications.
260
261   Filesystem Operations
262       In  order  to  effect one of the following operations, the pathname and
263       descriptor arguments passed to xfsctl() can be any open file in the XFS
264       filesystem in question.
265
266       XFS_IOC_FSINUMBERS
267              This  interface is used to extract a list of valid inode numbers
268              from an XFS filesystem.  It is  intended  to  be  called  itera‐
269              tively,  to obtain the entire set of inodes.  The information is
270              passed in and out via a  structure  of  type  xfs_fsop_bulkreq_t
271              pointed  to  by  the  final  argument.  lastip is a pointer to a
272              variable containing the last inode number returned, initially it
273              should  be  zero.  icount is the size of the array of structures
274              specified by ubuffer.  ubuffer is the address  of  an  array  of
275              structures,  of  type xfs_inogrp_t.  This structure has the fol‐
276              lowing elements: xi_startino (starting inode number),  xi_alloc‐
277              count  (count  of  bits  set  in xi_allocmask), and xi_allocmask
278              (mask of allocated inodes in this group).   The  bitmask  is  64
279              bits  long,  and  the least significant bit corresponds to inode
280              xi_startino.  Each bit is set if the corresponding inode  is  in
281              use.   ocount is a pointer to a count of returned values, filled
282              in by the call.  An output ocount value of zero means  that  the
283              inode table has been exhausted.
284
285       XFS_IOC_FSBULKSTAT
286              This interface is used to extract inode information (stat infor‐
287              mation) "in bulk" from a  filesystem.   It  is  intended  to  be
288              called  iteratively,  to obtain information about the entire set
289              of inodes in a filesystem.  The information is passed in and out
290              via  a  structure  of  type xfs_fsop_bulkreq_t pointed to by the
291              final argument.  lastip is a pointer to  a  variable  containing
292              the  last  inode  number  returned, initially it should be zero.
293              icount indicates the size of the array of  structures  specified
294              by ubuffer.  ubuffer is the address of an array of structures of
295              type xfs_bstat_t.  Many of the elements in the structure are the
296              same as for the stat structure.  The structure has the following
297              elements:  bs_ino  (inode  number),  bs_mode  (type  and  mode),
298              bs_nlink (number of links), bs_uid (user id), bs_gid (group id),
299              bs_rdev (device value), bs_blksize (block size of  the  filesys‐
300              tem),  bs_size  (file  size  in  bytes), bs_atime (access time),
301              bs_mtime (modify time), bs_ctime (inode change time),  bs_blocks
302              (number of blocks used by the file), bs_xflags (extended flags),
303              bs_extsize (extent size), bs_extents (number of extents), bs_gen
304              (generation  count),  bs_projid_lo  (project  id  -  low  word),
305              bs_projid_hi (project id - high word, used when projid32bit fea‐
306              ture  is  enabled),  bs_dmevmask  (DMIG  event mask), bs_dmstate
307              (DMIG state  information),  and  bs_aextents  (attribute  extent
308              count).   ocount  is  a  pointer  to a count of returned values,
309              filled in by the call.  An output ocount  value  of  zero  means
310              that the inode table has been exhausted.
311
312       XFS_IOC_FSBULKSTAT_SINGLE
313              This interface is a variant of the XFS_IOC_FSBULKSTAT interface,
314              used to obtain information about a single inode.   for  an  open
315              file  in the filesystem of interest.  The same structure is used
316              to pass information in and out of the kernel, except  no  output
317              count  parameter  is  used  (should be initialized to zero).  An
318              error is returned if the inode number is invalid.
319
320       XFS_IOC_THAW
321       XFS_IOC_FREEZE
322       XFS_IOC_GET_RESBLKS
323       XFS_IOC_SET_RESBLKS
324       XFS_IOC_FSGROWFSDATA
325       XFS_IOC_FSGROWFSLOG
326       XFS_IOC_FSGROWFSRT
327       XFS_IOC_FSCOUNTS
328              These interfaces are used to implement various filesystem inter‐
329              nal  operations on XFS filesystems.  For XFS_IOC_FSGEOMETRY (get
330              filesystem mkfs time information), the output  structure  is  of
331              type xfs_fsop_geom_t.  For XFS_FS_COUNTS (get filesystem dynamic
332              global  information),  the   output   structure   is   of   type
333              xfs_fsop_counts_t.   The  remainder of these operations will not
334              be described further as they are not of general use to  applica‐
335              tions.
336

SEE ALSO

338       fstatfs(2), statfs(2), xfs(5), xfs_info(8).
339
340
341
342                                                                     XFSCTL(3)
Impressum