vxfsio(7) Miscellaneous Information Manual vxfsio(7)
NAME
vxfsio - VxFS file system control functions
SYNOPSIS
DESCRIPTION
The ioctl(2) enhancements provide extended control for open files.
The argument is an open file descriptor.
The data type and value of are specific to the type of command specified by Unless specified, is treated as an type. The symbolic names
for commands and file status flags are defined by the header file.
The requirements for direct I/O are as follows:
o The starting file offset must be aligned to a 512-byte boundary.
o The ending file offset must be aligned to a 512-byte boundary, or the length must be a multiple of 512 bytes.
o The memory buffer must start on an 8-byte boundary.
If the I/O is performed using the and system calls, these restrictions apply to each element of the array of
The requirements to perform direct I/O on a given platform and operating system release may be less restrictive than above, but these
requirements are met, then direct I/O will work on any platform. In particular, HP-UX does not not require any alignment of the memory
buffer.
Also note that on HP-UX, direct I/O will be the most effi-cient if the starting and ending file offsets are aligned on file system block
boundaries, as reported in the field of
For an other than the ioctl, the argument is an open file descriptor. The data type and value of are specific to the type of command spec-
ified by
For the ioctl, the argument is an open file descriptor for any one of the file systems being frozen. The argument contains the count of
the number of file systems to be frozen, a list containing one open file descriptor for each file system being frozen, and a timeout value.
The symbolic names for commands and file status flags are defined by the header file.
Notes
In some cases, (see fsadm_vxfs(1M)) may reorganize the extent map of a file in such a way as to make it less contiguous. However, it does
not change the geometry of a file that has a fixed extent size.
Symbolic Names for Commands and Status Flags
The symbolic names for commands and file status flags are defined by the header file. The available VxFS ioctls are:
o VX_FREEZE
o VX_FREEZE_ALL
o VX_GET_IOPARAMETERS
o VX_GETCACHE
o VX_GETEXT
o VX_GETFSOPT
o VX_SETCACHE
o VX_SETEXT
o VX_THAW
Sync then freeze the file system.
Once frozen, all further operations against the file system block until a operation is received. The argument is a timeout value
expressed in seconds. If a operation is not received within the specified timeout interval, the file system performs a operation
automatically.
Only privileged users can run this command on the root directory of the file system.
The ioctl returns a zero if the file system is successfully frozen. If the operation fails, the return value is -1 and the external
variable is a general DIAGNOSTIC.
Sync then freeze multiple file systems.
This is identical to except that multiple file system can be specified.
Gets the I/O parameters for optimized application I/O.
The argument points to a structure of type as defined in The optimal I/O request sizes for applications using direct or discovered
direct I/O are returned in this structure. Applications using buffered I/O should use the value returned by for their I/O requests.
The ioctl returns a zero if the parameters are successfully obtained. If the operation fails, the return value is -1 and the exter-
nal variable is a general DIAGNOSTIC.
The fields in the structure are:
For an application to do efficient direct I/O or discovered direct I/O should issue read requests that are equal to the product of
multiplied by Generally any multiple or factor of multiplied by should be a good size for performance. For writing, the same for-
mula applies to the and parameters.
If an application is doing sequential I/O to large files, it should try to issue request larger than the discovered direct I/O size
for the file system. This causes the I/O requests to be performed as discovered direct I/O requests (which are unbuffered like
direct I/O but do not require synchronous inode updates when extending the file). If the file is larger than fits in the cache,
then using unbuffered I/O avoids throwing a lot of useful data out of the cache and it avoids a lot of CPU overhead. See the
vxtunefs(1M) manual page for more information on discovered direct I/O.
Get caching advisories in effect for the file.
The argument should be a pointer to an
The ioctl returns a zero if the caching advisories are successfully obtained and the advisories are returned in If the operation
fails, the return value is -1 and the external variable is a general DIAGNOSTIC.
Get extent information.
Return the extent information associated with The argument points to a structure of type as defined in Only persistent extent
attributes are visible.
The ioctl returns a zero if the extent information is successfully obtained. If the operation fails, the return value is -1 and the
external variable is a general DIAGNOSTIC.
Get file system options.
The argument fildes must be an open file descriptor of the root directory a VxFS file system. The argument should be a pointer
to an This command may be used by any user who can open the root inode on the file system. The options returned in are:
Indicates that all newly allocated blocks
are guaranteed to contain all zeros. (See the
Indicates that any non-logged changes
to the inode or data is flushed to disk when the file is closed.
Indicates that any non-synchronous I/O
is handled as if the cache advisory had been set on the file. Also, any non-logged changes to the inode or data is
flushed to disk when the file is closed.
Indicates that any writes
that do not have either or the advisory set is handled as if the advisory had been set on the file. Also, any non-logged
changes to the inode or data is flushed to disk when the file is closed.
Indicates that delayed extending writes have been disabled.
Non-logged changes to the inode or data is not flushed to disk when the file is closed.
Indicates that any non-synchronous I/O is handled as if the
cache advisory had been set on the file. Also, any non-logged changes to the inode or data is flushed to disk when the
file is closed.
Indicates that some system calls may return before the
intent log is written. (See the mount option of mount_vxfs(1M)).
Indicates that intent logging
of user data for synchronous writes is disabled.
Indicates that any non-logged changes
to the inode or data is flushed to disk when a file accessed with is closed.
Indicates that any
writes are delayed rather than to take effect immediately. No special action is taken when a file is closed.
Indicates that any
I/O is handled as if the cache advisory had been set on the file instead. Also, any non-logged changes to the inode or
data is flushed to disk when a file accessed with is closed.
Indicates that any
writes is handled as if the cache advisory had been set on the file instead. Also, any non-logged changes to the inode or
data is flushed to disk when a file accessed with is closed.
Indicates that any
I/O is handled as if the cache advisory had been set on the file. Also, any non-logged changes to the inode or data is
flushed to disk when a file accessed with is closed.
Indicates that a snapshot backup
of this file system is being maintained.
Indicates that this file system
is a snapshot backup of another file system.
Indicates that the intent log is almost always delayed.
(See the mount option of mount_vxfs(1M)).
Indicates that
the HP OnLineJFS product is not installed.
The ioctl returns a zero if the file system options are successfully obtained. If the operation fails, the return value is -1 and
the external variable is a general DIAGNOSTIC.
Set caching advisories.
These advisories allow an application to indicate to the file system which forms of caching are most advantageous.
The values for are such that multiple advisories may be set by combining values with bitwise operations. The possible values for
are
Indicates that data
associated with read and write operations is to be transferred directly to or from the user supplied buffer, without being
cached. When this option is enabled, all I/O operations must begin on block boundaries and must be a multiple of the
block size in length. The buffer supplied with the I/O operations must be aligned to a word boundary.
If an I/O request fails to meet alignment criteria, the I/O request is performed as a data synchronous I/O operation.
Indicates that data synchronous I/O mode is desired.
In data synchronous I/O mode, a write operation returns to the caller after the data has been transferred to external
media, but the inode is not updated synchronously if only the times in the inode need to be updated.
Indicates that buffered data
does not need to be retained in anticipation of further use by the application.
Indicates that the file is being accessed randomly.
Read-ahead should not be performed.
Indicates that the file is being accessed sequentially.
Maximum read-ahead should be performed.
Indicates that data associated with read and write operations is to be
transferred directly to or from the user supplied buffer, without being cached. The alignment constraints are identical to
those associated with the caching advisory.
If the file is extended or space is allocated to the file and the advisory is set, the inode is not written synchronously
to disk before the write returns.
The and caching advisories are mutually exclusive. Similarly, only one of the or caching advisories may be set.
The and caching advisories are maintained on a per-file basis. Changes made to these advisories by a process affect I/O operations
by all processes currently accessing the file.
The and caching advisories are maintained on a per-open instance of a file, so changes made to these advisories by a process do not
affect the setting of these advisories, and therefore I/O operations, by another process.
The ioctl returns a zero if the caching advisories are successfully set. If the operation fails, the return value is -1 and the
external variable is a general DIAGNOSTIC.
Set extent information.
Note: is available with the HP OnLineJFS product only.
The extent information is set according to the parameters specified by The argument points to a structure of type defined in This
structure contains the following members:
The element requests a fixed extent size, in blocks, for the file. If a fixed extent size is not required, use zero to allow the
default allocation policy to be used. Changes to the fixed extent size made after the file contains indirect blocks have no effect
unless all current indirect blocks are freed via file truncation and/or reservation deallocation.
The element sets the amount of space preallocated to the file (in blocks). If the amount is greater than the current reservation,
the allocation for the file is increased to match the amount. If the amount is less than the current reservation, the allocation is
decreased. The allocation is not reduced to less than the current file size.
File reservation cannot be increased beyond the ulimit (see ulimit(2)) of the requesting process. However, an existing reservation
is not trimmed to the requesting process's ulimit. Reservation of space for existing sparse files does not cause blocks to be allo-
cated to fill in the holes, but only allocates blocks after the end of the file. Thus, it is possible to have a larger reservation
for a file than blocks in the file.
The reservation amount is independent of file size since reservation is used to preallocate space for a file.
The element is used to indicate the type of reservation required. The choices are:
Align all new extents on an
boundary relative to the starting block of an allocation unit. If is also set, the single extent allocated during this
invocation is not subject to the alignment restriction.
The reservation is to be immediately incorporated
into the file. The file's on-disk inode is updated with the size and block count information that is increased to include
the reserved space. This operation is restricted to users with appropriate privileges.
The reservation must be allocated contiguously
(as a single extent). becomes the fixed extent size for subsequent allocations, but has no affect on this one. The
reservation fails if the file has gone into indirect extents, unless the amount of space requested is the same as the
indirect extent size. If the contiguous allocation request is done on an empty file, this does not happen.
The file may not be extended
once the current reservation is exceeded. The reservation may be increased if necessary by another invocation of the
ioctl, but the file is not automatically extended.
The reservation is to be made
as a non-persistent allocation to the file. The on-disk inode is not updated with the reservation information so that the
reservation does not survive a system crash. The reservation is associated with the file until the close of the file.
The reservation is trimmed to the current file size on close.
The reservation for the file
is to be trimmed to the current file size upon last close by all processes that have the file open.
Write permission to a file is required to set extent information, but any process that can open the file can get the extent informa-
tion. Extent information only applies to regular files. Only one set of extent information is kept per file. Only the and alloca-
tion flags are persistent attributes of the file. Other allocation flags may have persistent effects, but are not visible as allo-
cation flags. and are the only flags visible through the ioctl.
The ioctl returns a zero if the extent information is successfully set. If the operation fails, the return value is -1 and the
external variable is a general DIAGNOSTIC.
Unblock a file system
that has been frozen by a operation. The argument should be NULL. The process that is to issue a operation must have the root
directory of the file system open, and must ensure that it does not access the file system after the file system has been frozen, to
ensure that the process itself does not block.
Only privileged users can run this command on the root directory of the file system.
The ioctl returns a zero if the file system is successfully unfrozen. If the operation fails, the return value is -1 and the exter-
nal variable is a general DIAGNOSTIC or one of the diagnostics listed in the DIAGNOSTICS section.
DIAGNOSTICS
Operation failures can return any of the following values in
The calling process
does not have write access to the file specified by
The file system is not currently frozen.
The argument is not a valid file descriptor open for writing.
An address specified by an argument is invalid.
An attempt was made to reserve space
larger than the maximum file size limit for this process.
The command or argument is invalid.
An I/O error occurred while attempting to perform the operation.
The file specified by
is not the root directory of a file system.
Requested space could not be obtained.
The process does not have appropriate privilege.
The file system is mounted read-only.
The timeout expired before this call.
SEE ALSO
fsadm_vxfs(1M), mount_vxfs(1M), vxtunefs(1M), fcntl(2), getrlimit(2), ioctl(2), ulimit(2).
vxfsio(7)