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       XFS_IOC_FSGETXATTRA
91       XFS_IOC_FSSETXATTR
92              See ioctl_xfs_fsgetxattr(2) for more information.
93
94       XFS_IOC_GETBMAP
95       XFS_IOC_GETBMAPA
96       XFS_IOC_GETBMAPX
97              See ioctl_getbmap(2) for more information.
98
99       XFS_IOC_RESVSP
100       XFS_IOC_RESVSP64
101              This command is used to allocate space to a file.   A  range  of
102              bytes  is  specified  using  a  pointer  to  a  variable of type
103              xfs_flock64_t in the final argument.  The blocks are  allocated,
104              but  not  zeroed, and the file size does not change.  If the XFS
105              filesystem is configured to flag unwritten file extents, perfor‐
106              mance  will  be negatively affected when writing to preallocated
107              space, since extra filesystem transactions are required to  con‐
108              vert  extent  flags  on  the  range  of  the  file  written.  If
109              xfs_info(8) reports unwritten=1, then the filesystem was made to
110              flag unwritten extents.
111
112       XFS_IOC_UNRESVSP
113       XFS_IOC_UNRESVSP64
114              This  command  is  used  to  free space from a file.  A range of
115              bytes is specified  using  a  pointer  to  a  variable  of  type
116              xfs_flock64_t  in the final argument.  Partial filesystem blocks
117              are zeroed, and whole filesystem blocks  are  removed  from  the
118              file.  The file size does not change.
119
120       XFS_IOC_ZERO_RANGE
121              This command is used to convert a range of a file to zeros with‐
122              out issuing data IO.  A range of  bytes  is  specified  using  a
123              pointer  to  a variable of type xfs_flock64_t in the final argu‐
124              ment.  Blocks are preallocated for regions that  span  holes  in
125              the  file,  and  the  entire  range  is  converted  to unwritten
126              extents.  This operation is a fast  method  of  overwriting  any
127              from  the range specified with zeros without removing any blocks
128              or having to write zeros to disk.  Any subsequent  read  in  the
129              given  range  will return zeros until new data is written.  This
130              functionality requires filesystems to support unwritten extents.
131              If xfs_info(8) reports unwritten=1, then the filesystem was made
132              to flag unwritten extents.
133
134
135       XFS_IOC_PATH_TO_HANDLE
136       XFS_IOC_PATH_TO_FSHANDLE
137       XFS_IOC_FD_TO_HANDLE
138       XFS_IOC_OPEN_BY_HANDLE
139       XFS_IOC_READLINK_BY_HANDLE
140       XFS_IOC_ATTR_LIST_BY_HANDLE
141       XFS_IOC_ATTR_MULTI_BY_HANDLE
142       XFS_IOC_FSSETDM_BY_HANDLE
143              These are all interfaces that are used to implement various lib‐
144              handle  functions (see open_by_handle(3)).  They are all subject
145              to change and should not be called directly by applications.
146
147   Filesystem Operations
148       In order to effect one of the following operations,  the  pathname  and
149       descriptor arguments passed to xfsctl() can be any open file in the XFS
150       filesystem in question.
151
152       XFS_IOC_FSINUMBERS
153              See ioctl_xfs_fsinumbers(2) for more information.
154
155       XFS_IOC_FSGEOMETRY
156              See ioctl_xfs_fsop_geometry(2) for more information.
157
158       XFS_IOC_FSBULKSTAT or XFS_IOC_FSBULKSTAT_SINGLE
159              See ioctl_xfs_fsbulkstat(2) for more information.
160
161       XFS_IOC_SCRUB_METADATA
162              See ioctl_xfs_scrub_metadata(2) for more information.
163
164       XFS_IOC_FSCOUNTS
165              See ioctl_xfs_fscounts(2) for more information.
166
167       XFS_IOC_GET_RESBLKS
168       XFS_IOC_SET_RESBLKS
169              See ioctl_xfs_getresblks(2) for more information.  Save yourself
170              a lot of frustration and avoid these ioctls.
171
172       XFS_IOC_GOINGDOWN
173              See ioctl_xfs_goingdown(2) for more information.
174
175       XFS_IOC_THAW
176       XFS_IOC_FREEZE
177       XFS_IOC_FSGROWFSDATA
178       XFS_IOC_FSGROWFSLOG
179       XFS_IOC_FSGROWFSRT
180              These interfaces are used to implement various filesystem inter‐
181              nal operations on XFS filesystems.  The remainder of these oper‐
182              ations  will not be described further as they are not of general
183              use to applications.
184

SEE ALSO

186       ioctl_xfs_fsgetxattr(2), ioctl_xfs_fsop_geometry(2),  ioctl_xfs_fsbulk‐
187       stat(2),      ioctl_xfs_scrub_metadata(2),     ioctl_xfs_fsinumbers(2),
188       ioctl_xfs_fscounts(2),  ioctl_xfs_getresblks(2),  ioctl_xfs_getbmap(2),
189       ioctl_xfs_goingdown(2), fstatfs(2), statfs(2), xfs(5), xfs_info(8).
190
191
192
193                                                                     XFSCTL(3)
Impressum