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  and  fsx_extsize.   The fsx_xflags realtime file bit
170              and the file's extent size may be changed only when the file  is
171              empty,  except  in the case of a directory where the extent size
172              can be set at any time (this value is only used for regular file
173              allocations, so should only be set on a directory in conjunction
174              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
234       XFS_IOC_PATH_TO_HANDLE
235       XFS_IOC_PATH_TO_FSHANDLE
236       XFS_IOC_FD_TO_HANDLE
237       XFS_IOC_OPEN_BY_HANDLE
238       XFS_IOC_READLINK_BY_HANDLE
239       XFS_IOC_ATTR_LIST_BY_HANDLE
240       XFS_IOC_ATTR_MULTI_BY_HANDLE
241       XFS_IOC_FSSETDM_BY_HANDLE
242              These are all interfaces that are used to implement various lib‐
243              handle  functions (see open_by_handle(3)).  They are all subject
244              to change and should not be called directly by applications.
245
246   Filesystem Operations
247       In order to effect one of the following operations,  the  pathname  and
248       descriptor arguments passed to xfsctl() can be any open file in the XFS
249       filesystem in question.
250
251       XFS_IOC_FSINUMBERS
252              This interface is used to extract a list of valid inode  numbers
253              from  an  XFS  filesystem.   It  is intended to be called itera‐
254              tively, to obtain the entire set of inodes.  The information  is
255              passed  in  and  out  via a structure of type xfs_fsop_bulkreq_t
256              pointed to by the final argument.  lastip  is  a  pointer  to  a
257              variable containing the last inode number returned, initially it
258              should be zero.  icount is the size of the array  of  structures
259              specified  by  ubuffer.   ubuffer  is the address of an array of
260              structures, of type xfs_inogrp_t.  This structure has  the  fol‐
261              lowing  elements: xi_startino (starting inode number), xi_alloc‐
262              count (count of bits  set  in  xi_allocmask),  and  xi_allocmask
263              (mask  of  allocated  inodes  in this group).  The bitmask is 64
264              bits long, and the least significant bit  corresponds  to  inode
265              xi_startino.   Each  bit is set if the corresponding inode is in
266              use.  ocount is a pointer to a count of returned values,  filled
267              in  by  the call.  An output ocount value of zero means that the
268              inode table has been exhausted.
269
270       XFS_IOC_FSBULKSTAT
271              This interface is used to extract inode information (stat infor‐
272              mation)  "in  bulk"  from  a  filesystem.   It is intended to be
273              called iteratively, to obtain information about the  entire  set
274              of inodes in a filesystem.  The information is passed in and out
275              via a structure of type xfs_fsop_bulkreq_t  pointed  to  by  the
276              final  argument.   lastip  is a pointer to a variable containing
277              the last inode number returned, initially  it  should  be  zero.
278              icount  indicates  the size of the array of structures specified
279              by ubuffer.  ubuffer is the address of an array of structures of
280              type xfs_bstat_t.  Many of the elements in the structure are the
281              same as for the stat structure.  The structure has the following
282              elements:  bs_ino  (inode  number),  bs_mode  (type  and  mode),
283              bs_nlink (number of links), bs_uid (user id), bs_gid (group id),
284              bs_rdev  (device  value), bs_blksize (block size of the filesys‐
285              tem), bs_size (file size  in  bytes),  bs_atime  (access  time),
286              bs_mtime  (modify time), bs_ctime (inode change time), bs_blocks
287              (number of blocks used by the file), bs_xflags (extended flags),
288              bs_extsize (extent size), bs_extents (number of extents), bs_gen
289              (generation count), bs_projid (project  id),  bs_dmevmask  (DMIG
290              event  mask),  bs_dmstate  (DMIG state information), and bs_aex‐
291              tents (attribute extent count).  ocount is a pointer to a  count
292              of  returned  values,  filled  in by the call.  An output ocount
293              value of zero means that the inode table has been exhausted.
294
295       XFS_IOC_FSBULKSTAT_SINGLE
296              This interface is a variant of the XFS_IOC_FSBULKSTAT interface,
297              used  to  obtain  information about a single inode.  for an open
298              file in the filesystem of interest.  The same structure is  used
299              to  pass  information in and out of the kernel, except no output
300              count parameter is used (should be  initialized  to  zero).   An
301              error is returned if the inode number is invalid.
302
303       XFS_IOC_THAW
304       XFS_IOC_FREEZE
305       XFS_IOC_GET_RESBLKS
306       XFS_IOC_SET_RESBLKS
307       XFS_IOC_FSGROWFSDATA
308       XFS_IOC_FSGROWFSLOG
309       XFS_IOC_FSGROWFSRT
310       XFS_IOC_FSCOUNTS
311              These interfaces are used to implement various filesystem inter‐
312              nal operations on XFS filesystems.  For XFS_IOC_FSGEOMETRY  (get
313              filesystem  mkfs  time  information), the output structure is of
314              type xfs_fsop_geom_t.  For XFS_FS_COUNTS (get filesystem dynamic
315              global   information),   the   output   structure   is  of  type
316              xfs_fsop_counts_t.  The remainder of these operations  will  not
317              be  described further as they are not of general use to applica‐
318              tions.
319

SEE ALSO

321       fstatfs(2), statfs(2), xfs(5), xfs_info(8).
322
323
324
325                                                                     XFSCTL(3)
Impressum