From: Nathan Scott Date: Wed, 23 Apr 2003 00:30:48 +0000 (+0000) Subject: Update XFS-specific system call documentation, and fix includes. X-Git-Tag: XFS-1_3_0pre1~16 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=2e542de0b6567a05967791a83fd7fb124302d9c8;p=thirdparty%2Fxfsprogs-dev.git Update XFS-specific system call documentation, and fix includes. --- diff --git a/VERSION b/VERSION index ffa0cc7bf..678f35b87 100644 --- a/VERSION +++ b/VERSION @@ -3,5 +3,5 @@ # PKG_MAJOR=2 PKG_MINOR=4 -PKG_REVISION=6 +PKG_REVISION=7 PKG_BUILD=0 diff --git a/debian/changelog b/debian/changelog index ae1553383..c15aee392 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,8 +1,8 @@ -xfsprogs (2.4.5-1) unstable; urgency=low +xfsprogs (2.4.7-1) unstable; urgency=low * New upstream release - -- Nathan Scott Fri, 11 Apr 2003 16:18:27 +1000 + -- Nathan Scott Tue, 22 Apr 2003 16:58:14 +1000 xfsprogs (2.4.4-1) unstable; urgency=low diff --git a/doc/CHANGES b/doc/CHANGES index 08a1e6835..3891ca3a0 100644 --- a/doc/CHANGES +++ b/doc/CHANGES @@ -1,3 +1,6 @@ +xfsprogs-2.4.7 (22 April 2003) + - Clarify XFS system call interfaces, fix up documentation. + xfsprogs-2.4.6 (11 April 2003) - Fix a bug in detection of "clean" and "error" states with MD devices. diff --git a/include/libxfs.h b/include/libxfs.h index b900e220d..e6c45f427 100644 --- a/include/libxfs.h +++ b/include/libxfs.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000-2002 Silicon Graphics, Inc. All Rights Reserved. + * Copyright (c) 2000-2003 Silicon Graphics, Inc. All Rights Reserved. * * This program is free software; you can redistribute it and/or modify it * under the terms of version 2 of the GNU General Public License as @@ -32,45 +32,45 @@ #ifndef __LIBXFS_H__ #define __LIBXFS_H__ -#include "platform_defs.h" - -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include #ifndef XFS_SUPER_MAGIC #define XFS_SUPER_MAGIC 0x58465342 @@ -265,7 +265,7 @@ typedef struct xfs_buf_log_item { xfs_buf_log_format_t bli_format; /* in-log header */ } xfs_buf_log_item_t; -#include +#include typedef struct xfs_trans { unsigned int t_type; /* transaction type */ diff --git a/include/libxlog.h b/include/libxlog.h index 80ecee25f..3f6029ed2 100644 --- a/include/libxlog.h +++ b/include/libxlog.h @@ -32,7 +32,7 @@ #ifndef LIBXLOG_H #define LIBXLOG_H -#include +#include /* * define the userlevel xlog_t to be the subset of the kernel's @@ -60,10 +60,10 @@ typedef struct log { int l_grant_write_bytes; /* */ } xlog_t; -#include -#include -#include -#include +#include +#include +#include +#include /* * macros mapping kernel code to user code diff --git a/include/platform_defs.h.in b/include/platform_defs.h.in index 7a416fccb..d11f28d40 100644 --- a/include/platform_defs.h.in +++ b/include/platform_defs.h.in @@ -56,7 +56,7 @@ #include #include #include -#include "swab.h" +#include static __inline__ int xfsctl(const char *path, int fd, int cmd, void *p) { @@ -71,6 +71,14 @@ static __inline__ int platform_test_xfs_fd(int fd) return (buf.f_type == 0x58465342); /* XFSB */ } +static __inline__ int platform_test_xfs_path(const char *path) +{ + struct statfs buf; + if (statfs(path, &buf) < 0) + return 0; + return (buf.f_type == 0x58465342); /* XFSB */ +} + static __inline__ int platform_fstatfs(int fd, struct statfs *buf) { return fstatfs(fd, buf); @@ -181,6 +189,14 @@ static __inline__ int platform_test_xfs_fd(int fd) return (strcmp(buf.f_fstypename, "xfs") == 0); } +static __inline__ int platform_test_xfs_path(const char *path) +{ + struct statfs buf; + if (statfs(path, &buf) < 0) + return 0; + return (strcmp(buf.f_fstypename, "xfs") == 0); +} + static __inline__ int platform_fstatfs(int fd, struct statfs *buf) { return fstatfs(fd, buf); @@ -220,13 +236,13 @@ typedef unsigned char uchar_t; #define pwrite64 pwrite #define ftruncate64 ftruncate #define fdatasync fsync -#define memalign(a,sz) malloc(sz) +#define memalign(a,sz) valloc(sz) #include #define __BYTE_ORDER BYTE_ORDER #define __BIG_ENDIAN BIG_ENDIAN #define __LITTLE_ENDIAN LITTLE_ENDIAN -#include "swab.h" +#include #define O_LARGEFILE 0 #ifndef O_DIRECT @@ -283,7 +299,7 @@ typedef char* xfs_caddr_t; #define __BYTE_ORDER BYTE_ORDER #define __BIG_ENDIAN BIG_ENDIAN #define __LITTLE_ENDIAN LITTLE_ENDIAN -#include "swab.h" +#include #define INT_MAX INT32_MAX #define UINT_MAX UINT32_MAX @@ -307,6 +323,14 @@ static __inline__ int platform_test_xfs_fd(int fd) return (strcmp(sbuf.f_basetype, "xfs") == 0); } +static __inline__ int platform_test_xfs_path(const char *path) +{ + struct statvfs sbuf; + if (statvfs(path, &sbuf) < 0) + return 0; + return (strcmp(sbuf.f_basetype, "xfs") == 0); +} + static __inline__ int platform_fstatfs(int fd, struct statfs *buf) { return fstatfs(fd, buf, sizeof(struct statfs), 0); diff --git a/include/xqm.h b/include/xqm.h index fffdbec7d..66ace27ff 100644 --- a/include/xqm.h +++ b/include/xqm.h @@ -33,7 +33,7 @@ #ifndef __XQM_H__ #define __XQM_H__ -#include +#include /* * Disk quota - quotactl(2) commands for the XFS Quota Manager (XQM). diff --git a/man/man3/handle.3 b/man/man3/handle.3 index dacc6c8f3..3a2b5fda3 100644 --- a/man/man3/handle.3 +++ b/man/man3/handle.3 @@ -116,9 +116,8 @@ except that a handle is specified instead of a file descriptor. The \f2fssetdm_by_handle\f1() function sets the di_dmevmask and di_dmstate fields in an XFS on-disk inode. It is analogous to the \f2XFS_IOC_FSSETDM\f1 -.I ioctl(2) -command (see also -.I xfs(5)), except that a handle is specified instead of a file descriptor. +.I xfsctl(3) +command, except that a handle is specified instead of a file. .P The \f2free_handle\f1() function frees the storage allocated for handles @@ -129,10 +128,10 @@ and \f2handle_to_fshandle\f1(). .SH "SEE ALSO" open(2), -ioctl(2), readlink(2), attr_multi(3), attr_list(3), +xfsctl(3), xfs(5). .SH "DIAGNOSTICS" .PP diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3 new file mode 100644 index 000000000..c0559895f --- /dev/null +++ b/man/man3/xfsctl.3 @@ -0,0 +1,539 @@ +.TH XFSCTL 3 +.SH NAME +xfsctl \- control XFS filesystems and individual files +.SH C SYNOPSIS +.nf +.B #include +.PP +.B "int xfsctl (const char *path, int fd, int cmd, void *ptr); +.PP +.B "int platform_test_xfs_fd (int fd); +.B "int platform_test_xfs_path (const char *path); +.Op +.SH 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 +.I xfsctl +calls to ensure the target path and file descriptor do indeed +represent a file from an XFS filesystem. +The +.IR statfs (2) +and +.IR 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 +.I platform_test_xfs_fd +and +.I platform_test_xfs_path +provide a platform-independent mechanism. + +.SS FILE OPERATIONS +In order to effect an operation on an individual file, the pathname +and descriptor arguments passed to +.I xfsctl +identifies the file being operated on. +The final argument described below refers to the final argument of +.IR xfsctl . +All of the data structures and macros mentioned below are defined in the + header file. +.PP +.nf +.B XFS_IOC_FREESP +.B XFS_IOC_FREESP64 +.B XFS_IOC_ALLOCSP +.fi +.PD 0 +.TP +.B XFS_IOC_ALLOCSP64 +Alter storage space associated with a section of the ordinary +file specified. The section is specified by a variable of type +.BR xfs_flock64_t , +pointed to by the final argument. +The data type +.B xfs_flock64_t +contains the following members: +.B l_whence +is 0, 1, or 2 to indicate that the relative offset +.B l_start +will be measured from the start of the file, the current position, or +the end of the file, respectively. +.B l_start +is the offset from the position specified in +.BR l_whence . +.B l_len +is the size of the section. An +.B l_len +value of zero frees up to the end of the file; in this case, the end of +file (i.e., file size) is set to the beginning of the section freed. +Any data previously written into this section is no longer accessible. +If the section specified is beyond the current end of file, the file +is grown and filled with zeroes. +The +.B l_len +field is currently ignored, +and should be set to zero. + +.B XFS_IOC_FREESP +and +.BR XFS_IOC_FREESP64 +are identical, as are the +.B XFS_IOC_ALLOCSP +and +.BR XFS_IOC_ALLOCSP64 +operations. + +.TP +.B 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 +.B bs_dmevmask +and +.B bs_dmstate +fields of the bulkstat structure. +The data referred to by the final argument is a +.BR "struct fsdmidata" . +This structure's members are +.B fsd_dmevmask +and +.BR fsd_dmstate . +The di_dmevmask +field is set to the value in +.BR fsd_dmevmask . +The di_dmstate field is set to the value in +.BR 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 +aforementioned critical on-disk inode fields. + +.TP +.B 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 +.BR "struct dioattr" , +which contains the following members: +.B d_mem +is the memory alignment requirement of the user's data buffer. +.B 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. +.B 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 +.IR read (2) +or +.IR 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. + +.TP +.B XFS_IOC_FSGETXATTR +Get extended attributes associated with files in XFS file systems. +The final argument points to a variable of type +.BR "struct fsxattr" , +whose fields include: +.B fsx_xflags +(extended flag bits), +.B fsx_extsize +(nominal extent size in file system blocks), +.B fsx_nextents +(number of data extents in the file), +.B fsx_uuid +(file unique id). +Currently the only meaningful bits for the +.B fsx_xflags +field are bit 0 (value 1), which if set means the file is a realtime file, +and bit 1 (value 2), which if set means the file has preallocated space. +A +.B fsx_extsize +value returned indicates that a preferred extent size was previously +set on the file, a +.B fsx_extsize +of zero indicates that the defaults for that filesystem will be used. + +.TP +.B XFS_IOC_FSGETXATTRA +Identical to +.B XFS_IOC_FSGETXATTR +except that the +.B fsx_nextents +field contains the number of attribute extents in the file. + +.TP +.B XFS_IOC_FSSETXATTR +Set extended attributes associated with files in XFS file systems. +The final argument points to a variable of type +.BR "struct fsxattr" , +but only the following fields are used in this call: +.B fsx_xflags +and +.BR fsx_extsize . +The +.B fsx_xflags +realtime file bit, and the file's extent size, may be changed only +when the file is empty. + +.TP +.B 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 +.BR "struct getbmap" . +All sizes and offsets in the structure are in units of 512 bytes. +The structure fields include: +.B bmv_offset +(file offset of segment), +.B bmv_block +(starting block of segment), +.B bmv_length +(length of segment), +.B bmv_count +(number of array entries, including the first), and +.B 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 +.B XFS_IOC_GETBMAP +command. +The caller fills in the +.B bmv_offset +and +.B bmv_length +fields of the header to indicate the area of interest in the file, +and fills in the +.B bmv_count +field to indicate the length of the array. +If the +.B 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 +.B bmv_entries +field of the header is set to the number of array entries actually filled in. +The non-header structures will be filled in with +.BR bmv_offset , +.BR bmv_block , +and +.BR bmv_length . +If a region of the file has no blocks (is a hole in the file) then the +.B bmv_block +field is set to -1. + +.TP +.B XFS_IOC_GETBMAPA +Identical to +.B XFS_IOC_GETBMAP +except that information about the attribute fork of the file is returned. + +.PP +.nf +.B XFS_IOC_RESVSP +.fi +.TP +.B 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 +.B 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, +performance will be negatively affected when writing to preallocated space, +since extra filesystem transactions are required to convert extent flags on +the range of the file written. +If +.IR xfs_info (8) +reports unwritten=1, then the filesystem was made to flag unwritten extents. + +.PP +.nf +.B XFS_IOC_UNRESVSP +.fi +.TP +.B 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 +.B 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. + +.\" .TP +.\" .B XFS_IOC_GETBIOSIZE +.\" This command gets information about the preferred buffered I/O +.\" size used by the system when performing buffered I/O (e.g. +.\" standard Unix non-direct I/O) to and from the file. +.\" The information is passed back in a structure of type +.\" .B "struct biosize" +.\" pointed to by the final argument. +.\" biosize lengths are expressed in log base 2. +.\" That is if the value is 14, then the true size is 2^14 (2 raised to +.\" the 14th power). +.\" The +.\" .B biosz_read +.\" field will contain the current value used by the system when reading +.\" from the file. +.\" Except at the end-of-file, the system will read from the file in +.\" multiples of this length. +.\" The +.\" .B biosz_write +.\" field will contain the current value used by the system when writing +.\" to the file. +.\" Except at the end-of-file, the system will write to the file in +.\" multiples of this length. +.\" The +.\" .B dfl_biosz_read +.\" and +.\" .B dfl_biosz_write +.\" will be set to the system default values for the opened file. +.\" The +.\" .B biosz_flags +.\" field will be set to 1 if the current read or write value has been +.\" explicitly set. +.\" +.\" .TP +.\" .B XFS_IOC_SETBIOSIZE +.\" This command sets information about the preferred buffered I/O size +.\" used by the system when performing buffered I/O (e.g. standard Unix +.\" non-direct I/O) to and from the file. +.\" The information is passed in a structure of type +.\" .B "struct biosize" +.\" pointed to by the final argument. +.\" Using smaller preferred I/O sizes can result in performance +.\" improvements if the file is typically accessed using small +.\" synchronous I/Os or if only a small amount of the file is accessed +.\" using small random I/Os, resulting in little or no use of the +.\" additional data read in near the random I/Os. +.\" +.\" To explicitly set the preferred I/O sizes, the +.\" .B biosz_flags +.\" field should be set to zero and the +.\" .B biosz_read +.\" and +.\" .B biosz_write +.\" fields should be set to the log base 2 of the desired read and +.\" write lengths, respectively (e.g. 13 for 8K bytes, 14 for 16K +.\" bytes, 15 for 32K bytes, etc.). Valid values are 13-16 +.\" inclusive for machines with a 4K byte pagesize and 14-16 for +.\" machines with a 16K byte pagesize. The specified read and +.\" write values must also result in lengths that are greater than +.\" or equal to the filesystem block size. +.\" The +.\" .B dfl_biosz_read +.\" and +.\" .B dfl_biosz_write +.\" fields are ignored. +.\" +.\" If biosizes have already been explicitly set due to a prior use +.\" of +.\" .BR XFS_IOC_SETBIOSIZE , +.\" and the requested sizes are larger than the +.\" existing sizes, the +.\" .I xfsctl +.\" call will return successfully and the +.\" system will use the smaller of the two sizes. However, if +.\" .B biosz_flags +.\" is set to 1, the system will use the new values +.\" regardless of whether the new sizes are larger or smaller than the old. +.\" +.\" To reset the biosize values to the defaults for the filesystem +.\" that the file resides in, the +.\" .B biosz_flags +.\" field should be set to 2. +.\" The remainder of the fields will be ignored in that case. +.\" +.\" Changes made by +.\" .B XFS_IOC_SETBIOSIZE +.\" are transient. +.\" The sizes are reset to the default values once the reference count on the +.\" file drops to zero (e.g. all open file descriptors to that file +.\" have been closed). +.\" See +.\" .I mount(8) +.\" for details on how to set the +.\" default biosize values for a filesystem. + +.PP +.nf +.B XFS_IOC_PATH_TO_HANDLE +.B XFS_IOC_PATH_TO_FSHANDLE +.B XFS_IOC_FD_TO_HANDLE +.B XFS_IOC_OPEN_BY_HANDLE +.B XFS_IOC_READLINK_BY_HANDLE +.B XFS_IOC_ATTR_LIST_BY_HANDLE +.B XFS_IOC_ATTR_MULTI_BY_HANDLE +.fi +.PD 0 +.TP +.B XFS_IOC_FSSETDM_BY_HANDLE +These are all interfaces that are used to implement various +.I libhandle +functions (see +.IR open_by_handle (3)). +They are all subject to change and should not be called directly +by applications. + +.SS FILESYSTEM OPERATIONS +In order to effect one of the following operations, the pathname +and descriptor arguments passed to +.I xfsctl +can be any open file in the XFS filesystem in question. + +.PP +.TP +.B 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 iteratively, to obtain the entire set of inodes. +The information is passed in and out via a structure of type +.B xfs_fsop_bulkreq_t +pointed to by the final argument. +.B lastip +is a pointer to a variable containing the last inode number returned, +initially it should be zero. +.B icount +is the size of the array of structures specified by +.BR ubuffer . +.B ubuffer +is the address of an array of structures, of type +.BR xfs_inogrp_t . +This structure has the following elements: +.B xi_startino +(starting inode number), +.B xi_alloccount +(count of bits set in xi_allocmask), and +.B xi_allocmask +(mask of allocated inodes in this group). +The bitmask is 64 bits long, and the least significant bit corresponds to inode +.B xi_startino. +Each bit is set if the corresponding inode is in use. +.B ocount +is a pointer to a count of returned values, filled in by the call. +An output +.B ocount +value of zero means that the inode table has been exhausted. + +.TP +.B XFS_IOC_FSBULKSTAT +This interface is used to extract inode information (stat +information) "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 +.B xfs_fsop_bulkreq_t +pointed to by the final argument. +.B lastip +is a pointer to a variable containing the last inode number returned, +initially it should be zero. +.B icount +indicates the size of the array of structures specified by +.B ubuffer. +.B ubuffer +is the address of an array of structures of type +.BR xfs_bstat_t . +Many of the elements in the structure are the same as for the stat +structure. +The structure has the following elements: +.B bs_ino +(inode number), +.B bs_mode +(type and mode), +.B bs_nlink +(number of links), +.B bs_uid +(user id), +.B bs_gid +(group id), +.B bs_rdev +(device value), +.B bs_blksize +(block size of the filesystem), +.B bs_size +(file size in bytes), +.B bs_atime +(access time), +.B bs_mtime +(modify time), +.B bs_ctime +(inode change time), +.B bs_blocks +(number of blocks used by the file), +.B bs_xflags +(extended flags), +.B bs_extsize +(extent size), +.B bs_extents +(number of extents), +.B bs_gen +(generation count), +.B bs_projid +(project id), +.B bs_dmevmask +(DMIG event mask), +.B bs_dmstate +(DMIG state information), and +.B bs_aextents +(attribute extent count). +.B ocount +is a pointer to a count of returned values, filled in by the call. +An output +.B ocount +value of zero means that the inode table has been exhausted. + +.TP +.B XFS_IOC_FSBULKSTAT_SINGLE +This interface is a variant of the +.B 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. + +.PP +.nf +.B XFS_IOC_THAW +.B XFS_IOC_FREEZE +.B XFS_IOC_GET_RESBLKS +.B XFS_IOC_SET_RESBLKS +.B XFS_IOC_FSGROWFSDATA +.B XFS_IOC_FSGROWFSLOG +.B XFS_IOC_FSGROWFSRT +.fi +.TP +.B XFS_IOC_FSCOUNTS +These interfaces are used to implement various filesystem internal +operations on XFS filesystems. +For +.B XFS_IOC_FSGEOMETRY +(get filesystem mkfs time information), the output structure is of type +.BR xfs_fsop_geom_t . +For +.B XFS_FS_COUNTS +(get filesystem dynamic global information), the output structure is of type +.BR xfs_fsop_counts_t . +The remainder of these operations will not be described further +as they are not of general use to applications. + +.SH SEE ALSO +fstatfs(2), +statfs(2), +xfs(5), +xfs_info(8). diff --git a/man/man5/xfs.5 b/man/man5/xfs.5 index 10d048588..b3bb56686 100644 --- a/man/man5/xfs.5 +++ b/man/man5/xfs.5 @@ -90,526 +90,15 @@ may become confused when doing incremental and resumed dumps. and .I xfsrestore are recommended for making copies of XFS filesystems. + .SH OPERATIONS Some functionality specific to the XFS filesystem is accessible to -applications through the Linux -.IR ioctl (2) -interface. -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 these XFS -.I ioctl -calls to ensure the target file descriptor does indeed represent a -file from an XFS filesystem. -The -.IR fstatfs (2) -system call can be used to determine whether or not an arbitrary -file descriptor belongs to an XFS filesystem. - -.SS FILE OPERATIONS -In order to effect an operation on an individual file, the descriptor -argument passed to -.I ioctl -identifies the file being operated on. -The third argument described below refers to the third argument of the -.I ioctl -system call (which is traditionally a -.B "char *" -or -.BR "void *" ). -All of the data structures and macros mentioned below are defined in the - header file. -.PP -.nf -.B XFS_IOC_FREESP -.B XFS_IOC_FREESP64 -.B XFS_IOC_ALLOCSP -.fi -.PD 0 -.TP -.B XFS_IOC_ALLOCSP64 -Alter storage space associated with a section of the ordinary -file fildes. The section is specified by a variable of type -.BR xfs_flock64_t , -pointed to by the third argument. -The data type -.B xfs_flock64_t -contains the following members: -.B l_whence -is 0, 1, or 2 to indicate that the relative offset -.B l_start -will be measured from the start of the file, the current position, or -the end of the file, respectively. -.B l_start -is the offset from the position specified in -.BR l_whence . -.B l_len -is the size of the section. An -.B l_len -value of zero frees up to the end of the file; in this case, the end of -file (i.e., file size) is set to the beginning of the section freed. -Any data previously written into this section is no longer accessible. -If the section specified is beyond the current end of file, the file -is grown and filled with zeroes. -The -.B l_len -field is currently ignored, -and should be set to zero. - -.B XFS_IOC_FREESP -and -.BR XFS_IOC_FREESP64 -are identical, as are the -.B XFS_IOC_ALLOCSP -and -.BR XFS_IOC_ALLOCSP64 -operations. - -.TP -.B 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 -.B bs_dmevmask -and -.B bs_dmstate -fields of the bulkstat structure. -The data referred to by the third argument is a -.BR "struct fsdmidata" . -This structure's members are -.B fsd_dmevmask -and -.BR fsd_dmstate . -The di_dmevmask -field is set to the value in -.BR fsd_dmevmask . -The di_dmstate field is set to the value in -.BR 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 -aforementioned critical on-disk inode fields. - -.TP -.B 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 third argument points to a variable of type -.BR "struct dioattr" , -which contains the following members: -.B d_mem -is the memory alignment requirement of the user's data buffer. -.B 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. -.B 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 -.IR read (2) -or -.IR 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. - -.TP -.B XFS_IOC_FSGETXATTR -Get extended attributes associated with files in XFS file systems. -The third argument points to a variable of type -.BR "struct fsxattr" , -whose fields include: -.B fsx_xflags -(extended flag bits), -.B fsx_extsize -(nominal extent size in file system blocks), -.B fsx_nextents -(number of data extents in the file), -.B fsx_uuid -(file unique id). -Currently the only meaningful bits for the -.B fsx_xflags -field are bit 0 (value 1), which if set means the file is a realtime file, -and bit 1 (value 2), which if set means the file has preallocated space. -A -.B fsx_extsize -value returned indicates that a preferred extent size was previously -set on the file, a -.B fsx_extsize -of zero indicates that the defaults for that filesystem will be used. - -.TP -.B XFS_IOC_FSGETXATTRA -Identical to -.B XFS_IOC_FSGETXATTR -except that the -.B fsx_nextents -field contains the number of attribute extents in the file. - -.TP -.B XFS_IOC_FSSETXATTR -Set extended attributes associated with files in XFS file systems. -The third argument points to a variable of type -.BR "struct fsxattr" , -but only the following fields are used in this call: -.B fsx_xflags -and -.BR fsx_extsize . -The -.B fsx_xflags -realtime file bit, and the file's extent size, may be changed only -when the file is empty. - -.TP -.B XFS_IOC_GETBMAP -Get the block map for a segment of a file in an XFS file system. -The third argument points to an arry of variables of type -.BR "struct getbmap" . -All sizes and offsets in the structure are in units of 512 bytes. -The structure fields include: -.B bmv_offset -(file offset of segment), -.B bmv_block -(starting block of segment), -.B bmv_length -(length of segment), -.B bmv_count -(number of array entries, including the first), and -.B 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 -.B XFS_IOC_GETBMAP -command. -The caller fills in the -.B bmv_offset +applications through the +.IR xfsctl (3) and -.B bmv_length -fields of the header to indicate the area of interest in the file, -and fills in the -.B bmv_count -field to indicate the length of the array. -If the -.B 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 -.B bmv_entries -field of the header is set to the number of array entries actually filled in. -The non-header structures will be filled in with -.BR bmv_offset , -.BR bmv_block , -and -.BR bmv_length . -If a region of the file has no blocks (is a hole in the file) then the -.B bmv_block -field is set to -1. - -.TP -.B XFS_IOC_GETBMAPA -Identical to -.B XFS_IOC_GETBMAP -except that information about the attribute fork of the file is returned. - -.PP -.nf -.B XFS_IOC_RESVSP -.fi -.TP -.B 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 -.B xfs_flock64_t -in the third 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, -performance will be negatively affected when writing to preallocated space, -since extra filesystem transactions are required to convert extent flags on -the range of the file written. -If -.IR xfs_info (8) -reports unwritten=1, then the filesystem was made to flag unwritten extents. - -.PP -.nf -.B XFS_IOC_UNRESVSP -.fi -.TP -.B 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 -.B xfs_flock64_t -in the third argument. -Partial filesystem blocks are zeroed, and whole filesystem blocks are -removed from the file. The file size does not change. - -.\" .TP -.\" .B XFS_IOC_GETBIOSIZE -.\" This command gets information about the preferred buffered I/O -.\" size used by the system when performing buffered I/O (e.g. -.\" standard Unix non-direct I/O) to and from the file. -.\" The information is passed back in a structure of type -.\" .B "struct biosize" -.\" pointed to by the third argument. -.\" biosize lengths are expressed in log base 2. -.\" That is if the value is 14, then the true size is 2^14 (2 raised to -.\" the 14th power). -.\" The -.\" .B biosz_read -.\" field will contain the current value used by the system when reading -.\" from the file. -.\" Except at the end-of-file, the system will read from the file in -.\" multiples of this length. -.\" The -.\" .B biosz_write -.\" field will contain the current value used by the system when writing -.\" to the file. -.\" Except at the end-of-file, the system will write to the file in -.\" multiples of this length. -.\" The -.\" .B dfl_biosz_read -.\" and -.\" .B dfl_biosz_write -.\" will be set to the system default values for the opened file. -.\" The -.\" .B biosz_flags -.\" field will be set to 1 if the current read or write value has been -.\" explicitly set. -.\" -.\" .TP -.\" .B XFS_IOC_SETBIOSIZE -.\" This command sets information about the preferred buffered I/O size -.\" used by the system when performing buffered I/O (e.g. standard Unix -.\" non-direct I/O) to and from the file. -.\" The information is passed in a structure of type -.\" .B "struct biosize" -.\" pointed to by the third argument. -.\" Using smaller preferred I/O sizes can result in performance -.\" improvements if the file is typically accessed using small -.\" synchronous I/Os or if only a small amount of the file is accessed -.\" using small random I/Os, resulting in little or no use of the -.\" additional data read in near the random I/Os. -.\" -.\" To explicitly set the preferred I/O sizes, the -.\" .B biosz_flags -.\" field should be set to zero and the -.\" .B biosz_read -.\" and -.\" .B biosz_write -.\" fields should be set to the log base 2 of the desired read and -.\" write lengths, respectively (e.g. 13 for 8K bytes, 14 for 16K -.\" bytes, 15 for 32K bytes, etc.). Valid values are 13-16 -.\" inclusive for machines with a 4K byte pagesize and 14-16 for -.\" machines with a 16K byte pagesize. The specified read and -.\" write values must also result in lengths that are greater than -.\" or equal to the filesystem block size. -.\" The -.\" .B dfl_biosz_read -.\" and -.\" .B dfl_biosz_write -.\" fields are ignored. -.\" -.\" If biosizes have already been explicitly set due to a prior use -.\" of -.\" .BR XFS_IOC_SETBIOSIZE , -.\" and the requested sizes are larger than the -.\" existing sizes, the -.\" .I ioctl -.\" call will return successfully and the -.\" system will use the smaller of the two sizes. However, if -.\" .B biosz_flags -.\" is set to 1, the system will use the new values -.\" regardless of whether the new sizes are larger or smaller than the old. -.\" -.\" To reset the biosize values to the defaults for the filesystem -.\" that the file resides in, the -.\" .B biosz_flags -.\" field should be set to 2. -.\" The remainder of the fields will be ignored in that case. -.\" -.\" Changes made by -.\" .B XFS_IOC_SETBIOSIZE -.\" are transient. -.\" The sizes are reset to the default values once the reference count on the -.\" file drops to zero (e.g. all open file descriptors to that file -.\" have been closed). -.\" See -.\" .I mount(8) -.\" for details on how to set the -.\" default biosize values for a filesystem. - -.PP -.nf -.B XFS_IOC_PATH_TO_HANDLE -.B XFS_IOC_PATH_TO_FSHANDLE -.B XFS_IOC_FD_TO_HANDLE -.B XFS_IOC_OPEN_BY_HANDLE -.B XFS_IOC_READLINK_BY_HANDLE -.B XFS_IOC_ATTR_LIST_BY_HANDLE -.B XFS_IOC_ATTR_MULTI_BY_HANDLE -.fi -.PD 0 -.TP -.B XFS_IOC_FSSETDM_BY_HANDLE -These are all interfaces that are used to implement various -.I libhandle -functions (see -.IR fd_to_handle (3)). -They are all subject to change and should not be called directly -by applications. - -.SS FILESYSTEM OPERATIONS -In order to effect one of the following operations, the file descriptor -argument passed to -.I ioctl -can be any open file in the XFS filesystem in question. - -.PP -.TP -.B 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 iteratively, to obtain the entire set of inodes. -The information is passed in and out via a structure of type -.B xfs_fsop_bulkreq_t -pointed to by the third argument. -.B lastip -is a pointer to a variable containing the last inode number returned, -initially it should be zero. -.B icount -is the size of the array of structures specified by -.BR ubuffer . -.B ubuffer -is the address of an array of structures, of type -.BR xfs_inogrp_t . -This structure has the following elements: -.B xi_startino -(starting inode number), -.B xi_alloccount -(count of bits set in xi_allocmask), and -.B xi_allocmask -(mask of allocated inodes in this group). -The bitmask is 64 bits long, and the least significant bit corresponds to inode -.B xi_startino. -Each bit is set if the corresponding inode is in use. -.B ocount -is a pointer to a count of returned values, filled in by the call. -An output -.B ocount -value of zero means that the inode table has been exhausted. - -.TP -.B XFS_IOC_FSBULKSTAT -This interface is used to extract inode information (stat -information) "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 -.B xfs_fsop_bulkreq_t -pointed to by the third argument. -.B lastip -is a pointer to a variable containing the last inode number returned, -initially it should be zero. -.B icount -indicates the size of the array of structures specified by -.B ubuffer. -.B ubuffer -is the address of an array of structures of type -.BR xfs_bstat_t . -Many of the elements in the structure are the same as for the stat -structure. -The structure has the following elements: -.B bs_ino -(inode number), -.B bs_mode -(type and mode), -.B bs_nlink -(number of links), -.B bs_uid -(user id), -.B bs_gid -(group id), -.B bs_rdev -(device value), -.B bs_blksize -(block size of the filesystem), -.B bs_size -(file size in bytes), -.B bs_atime -(access time), -.B bs_mtime -(modify time), -.B bs_ctime -(inode change time), -.B bs_blocks -(number of blocks used by the file), -.B bs_xflags -(extended flags), -.B bs_extsize -(extent size), -.B bs_extents -(number of extents), -.B bs_gen -(generation count), -.B bs_projid -(project id), -.B bs_dmevmask -(DMIG event mask), -.B bs_dmstate -(DMIG state information), and -.B bs_aextents -(attribute extent count). -.B ocount -is a pointer to a count of returned values, filled in by the call. -An output -.B ocount -value of zero means that the inode table has been exhausted. - -.TP -.B XFS_IOC_FSBULKSTAT_SINGLE -This interface is a variant of the -.B 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. - -.PP -.nf -.B XFS_IOC_THAW -.B XFS_IOC_FREEZE -.B XFS_IOC_GET_RESBLKS -.B XFS_IOC_SET_RESBLKS -.B XFS_IOC_FSGROWFSDATA -.B XFS_IOC_FSGROWFSLOG -.B XFS_IOC_FSGROWFSRT -.fi -.TP -.B XFS_IOC_FSCOUNTS -These interfaces are used to implement various filesystem internal -operations on XFS filesystems. -For -.B XFS_IOC_FSGEOMETRY -(get filesystem mkfs time information), the output structure is of type -.BR xfs_fsop_geom_t . -For -.B XFS_FS_COUNTS -(get filesystem dynamic global information), the output structure is of type -.BR xfs_fsop_counts_t . -The remainder of these operations will not be described further -as they are not of general use to applications. +by-handle (see +.IR open_by_handle (3)) +interfaces. .SH MOUNT OPTIONS Refer to the @@ -617,8 +106,7 @@ Refer to the manual entry for descriptions of the individual XFS mount options. .SH SEE ALSO -ioctl(2), -fstatfs(2), +xfsctl(3), mount(8), mkfs.xfs(8), xfs_info(8),