vxfsio(7)vxfsio(7)NAMEvxfsio - VxFS file system control functions
SYNOPSISDESCRIPTION
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 speci‐
fied 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:
· The starting file offset must be aligned to a 512-byte boundary.
· The ending file offset must be aligned to a 512-byte boundary, or
the length must be a multiple of 512 bytes.
· 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 operat‐
ing 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 buf‐
fer.
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 statvfs(2).
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 speci‐
fied 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:
· VX_FREEZE
· VX_FREEZE_ALL
· VX_GET_IOPARAMETERS
· VX_GETCACHE
· VX_GETEXT
· VX_GETFSOPT
· VX_SETCACHE
· VX_SETEXT
· 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 dis‐
covered 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 external 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 writ‐
ing, the same formula 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 success‐
fully obtained and the advisories are returned in If the opera‐
tion 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 success‐
fully 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 mount
option of mount_vxfs(1M)).
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 immedi‐
ately. 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 success‐
fully 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 buf‐
fer, without being cached. When this option is
enabled, all I/O operations must begin on block bound‐
aries 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 trans‐
ferred 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 fur‐
ther 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 buf‐
fer, 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 opera‐
tions 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 success‐
fully set. If the operation fails, the return value is -1 and
the external variable is a general DIAGNOSTIC.
Set extent information.
The extent information is set according to the parameters speci‐
fied 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 reserva‐
tion, 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 allocated 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 reser‐
vation 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 alloca‐
tion unit. If is also set, the single extent allo‐
cated 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 opera‐
tion is restricted to users with appropriate privi‐
leges.
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 con‐
tiguous 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 reser‐
vation may be increased if necessary by another invo‐
cation 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 infor‐
mation so that the reservation does not survive a sys‐
tem 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 informa‐
tion, but any process that can open the file can get the extent
information. Extent information only applies to regular files.
Only one set of extent information is kept per file. Only the
and allocation flags are persistent attributes of the file.
Other allocation flags may have persistent effects, but are not
visible as allocation flags. and are the only flags visible
through the ioctl.
The ioctl returns a zero if the extent information is success‐
fully 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 external 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 ALSOfsadm_vxfs(1M), mount_vxfs(1M), vxtunefs(1M), fcntl(2), getrlimit(2),
ioctl(2), ulimit(2).
vxfsio(7)
