vxfsio(7) vxfsio(7)
NAME [Toc] [Back]
vxfsio - VxFS file system control functions
SYNOPSIS [Toc] [Back]
#include <sys/types.h>
#include <sys/fs/vx_ioctl.h>
int ioctl(int fildes, int cmd, ... /* arg */);
DESCRIPTION [Toc] [Back]
The vxfs ioctl(2) enhancements provide for extended control over open
files.
The argument fildes is an open file descriptor.
The data type and value of arg are specific to the type of command
specified by cmd. Unless specified, arg is treated as an int type.
The symbolic names for commands and file status flags are defined by
the sys/fs/vx_ioctl.h header file.
Notes [Toc] [Back]
In some cases, fsadm_vxfs(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 [Toc] [Back]
The symbolic names for commands and file status flags are defined by
the sys/fs/vx_ioctl.h header file. The available VxFS ioctls are:
+ VX_FREEZE
+ VX_GET_IOPARAMETERS
+ VX_GETCACHE
+ VX_GETEXT
+ VX_GETFSOPT
+ VX_SETCACHE
+ VX_SETEXT
+ VX_THAW
VX_FREEZE [Toc] [Back]
Sync then freeze the file system. Once frozen, all further
operations against the file system block until a VX_THAW
operation is received. The argument arg is a timeout value
expressed in seconds. If a VX_THAW operation is not received
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
vxfsio(7) vxfsio(7)
within the specified timeout interval, the file system performs a
VX_THAW operation automatically.
Only privileged users can run this command on the root directory
of the file system.
The VX_FREEZE ioctl returns a zero if the file system is
successfully frozen. If the operation fails, the return value is
-1 and the external variable errno is a general DIAGNOSTIC.
VX_GET_IOPARAMETERS [Toc] [Back]
Get the I/O parameters for optimized application I/O. The
argument arg points to a structure of type vx_ioparameters as
defined in sys/fs/vxio.h. 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 st_blksize value returned by stat for their I/O requests.
The VX_GET_IOPARAMETERS ioctl returns a zero if the parameters
are successfully obtained. If the operation fails, the return
value is -1 and the external variable errno is a general
DIAGNOSTIC.
The fields in the vx_ioparameters structure are:
size_t vi_read_preferred_io; /* preferred read size in bytes */
size_t vi_read_nstream; /* num of preferred reads to stream */
size_t vi_read_unit_io; /* less preferred read size in bytes */
size_t vi_write_preferred_io; /* preferred write size in bytes */
size_t vi_write_nstream; /* num of preferred writes to stream */
size_t vi_write_unit_io; /* less preferred write size in bytes */
size_t vi_pref_strength; /* strength of preferences */
size_t vi_breakup_size; /* I/O breakup size in bytes */
size_t vi_align_offset; /* adj for alignment calculations */
dev_t vi_block_device; /* bdev number for this cdev */
An application that tries to do efficient direct I/O or
discovered direct I/O should issue read requests that are equal
to the product of vi_read_nstream multiplied by
vi_read_preferred_io. Generally any multiple or factor of
vi_read_nstream multiplied by vi_read_preferred_io should be a
good size for performance. For writing, the same rule of thumb
applies to the vi_write_preferred_io and vi_write_nstream
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
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
vxfsio(7) vxfsio(7)
the vxtunefs(1M) manual page for more information on discovered
direct I/O.
VX_GETCACHE [Toc] [Back]
Get caching advisories in effect for the file. The argument arg
should be a pointer to an int.
The VX_GETCACHE ioctl returns a zero if the caching advisories
are successfully obtained and the advisories are returned in arg.
If the operation fails, the return value is -1 and the external
variable errno is a general DIAGNOSTIC.
VX_GETEXT [Toc] [Back]
Get extent information. Return the extent information associated
with fildes. The argument arg points to a structure of type
vx_ext as defined in sys/fs/vx_ioctl.h. Only persistent extent
attributes are visible.
The VX_GETEXT ioctl returns a zero if the extent information is
successfully obtained. If the operation fails, the return value
is -1 and the external variable errno is a general DIAGNOSTIC.
VX_GETFSOPT [Toc] [Back]
Get file system options. The argument arg should be a pointer to
an int. This command may be used by any user who can open the
root inode on the file system. The options returned in arg are:
VX_FSO_BLKCLEAR [Toc] [Back]
Indicates that all newly allocated blocks are
guaranteed to contain all zeros. (See the blkclear
mount option of mount_vxfs(1M)).
VX_FSO_CACHE_CLOSESYNC [Toc] [Back]
Indicates that any non-logged changes to the inode or
data is flushed to disk when the file is closed. (See
the mincache=closesync mount option of mount_vxfs(1M)).
VX_FSO_CACHE_DIRECT [Toc] [Back]
Indicates that any non-synchronous I/O is handled as if
the VX_DIRECT 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. (See the
mincache=direct mount option of mount_vxfs(1M)).
VX_FSO_CACHE_DSYNC [Toc] [Back]
Indicates that any writes that do not have either
O_SYNC or the VX_DIRECT advisory set is handled as if
the VX_DSYNC 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. (See the
mincache=dsync mount option of mount_vxfs(1M)).
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
vxfsio(7) vxfsio(7)
VX_FSO_CACHE_TMPCACHE [Toc] [Back]
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. (See the
mincache=tmpcache mount option of mount_vxfs(1M)).
VX_FSO_CACHE_UNBUFFERED [Toc] [Back]
Indicates that any non-synchronous I/O is handled as if
the VX_UNBUFFERED 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. (See
the mincache=unbuffered mount option of
mount_vxfs(1M)).
VX_FSO_DELAYLOG [Toc] [Back]
Indicates that some system calls may return before the
intent log is written. (See the delaylog mount option
of mount_vxfs(1M)).
VX_FSO_NODATAINLOG [Toc] [Back]
Indicates that intent logging of user data for
synchronous writes is disabled. (See the nodatainlog
mount option of mount_vxfs(1M)).
VX_FSO_NOLOG [Toc] [Back]
Indicates that intent logging of structural changes to
the file system is disabled. (See the nolog mount
option of mount_vxfs(1M)).
VX_FSO_OSYNC_CLOSESYNC [Toc] [Back]
Indicates that any non-logged changes to the inode or
data is flushed to disk when a file accessed with
O_SYNC is closed. (See the convosync=closesync mount
option of mount_vxfs(1M)).
VX_FSO_OSYNC_DELAY [Toc] [Back]
Indicates that any O_SYNC writes is delayed rather than
to take effect immediately. No special action is taken
when a file is closed.
VX_FSO_OSYNC_DIRECT [Toc] [Back]
Indicates that any O_SYNC I/O is handled as if the
VX_DIRECT 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
O_SYNC is closed. (See the convosync=direct mount
option of mount_vxfs(1M)).
VX_FSO_OSYNC_DSYNC [Toc] [Back]
Indicates that any O_SYNC writes is handled as if the
VX_DSYNC cache advisory had been set on the file
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
vxfsio(7) vxfsio(7)
instead. Also, any non-logged changes to the inode or
data is flushed to disk when a file accessed with
O_SYNC is closed. (See the convosync=dsync mount
option of mount_vxfs(1M)).
VX_FSO_OSYNC_UNBUFFERED [Toc] [Back]
Indicates that any O_SYNC I/O is handled as if the
VX_UNBUFFERED 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 O_SYNC is
closed. (See the convosync=unbuffered mount option of
mount_vxfs(1M)).
VX_FSO_SNAPPED [Toc] [Back]
Indicates that a snapshot backup of this file system is
being maintained.
VX_FSO_SNAPSHOT [Toc] [Back]
Indicates that this file system is a snapshot backup of
another file system.
VX_FSO_TMPLOG [Toc] [Back]
Indicates that the intent log is almost always delayed.
(See the tmplog mount option of mount_vxfs(1M)).
VX_FSO_VJFS [Toc] [Back]
Indicates that the HP OnLineJFS product is not
installed.
The VX_GETFSOPT 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 errno is a general
DIAGNOSTIC.
VX_SETCACHE [Toc] [Back]
Set caching advisories. These advisories allow an application to
indicate to the file system which forms of caching are most
advantageous.
Note: VX_SETCACHE is available with the HP OnLineJFS product
only.
The values for arg are such that multiple advisories may be set
by combining values with bitwise OR operations. The possible
values for arg are
VX_DIRECT [Toc] [Back]
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
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
vxfsio(7) vxfsio(7)
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.
VX_DSYNC [Toc] [Back]
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.
VX_NOREUSE [Toc] [Back]
Indicates that buffered data does not need to be
retained in anticipation of further use by the
application.
VX_RANDOM [Toc] [Back]
Indicates that the file is being accessed randomly.
Read-ahead should not be performed.
VX_SEQ [Toc] [Back]
Indicates that the file is being accessed sequentially.
Maximum read-ahead should be performed.
VX_UNBUFFERED [Toc] [Back]
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 VX_DIRECT caching advisory.
If the file is extended or space is allocated to the
file and the VX_UNBUFFERED advisory is set, the inode
is not written synchronously to disk before the write
returns.
The VX_RANDOM and VX_SEQ caching advisories are mutually
exclusive. Similarly, only one of the VX_DIRECT, VX_DSYNC, or
VX_UNBUFFERED caching advisories may be set.
The VX_RANDOM, VX_SEQ, and VX_NOREUSE 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.
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
vxfsio(7) vxfsio(7)
The VX_DIRECT, VX_DSYNC, and VX_UNBUFFERED 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 VX_SETCACHE ioctl returns a zero if the caching advisories
are successfully set. If the operation fails, the return value
is -1 and the external variable errno is a general DIAGNOSTIC.
VX_SETEXT [Toc] [Back]
Set extent information.
Note: VX_SETEXT is available with the HP OnLineJFS product only.
The extent information is set according to the parameters
specified by arg. The argument arg points to a structure of type
vx_ext defined in sys/fs/vx_ioctl.h. This structure contains the
following members:
ext_size
reserve
a_flags
The ext_size 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 reserve element sets the amount of space preallocated to the
file (in blocks). If the reserve amount is greater than the
current reservation, the allocation for the file is increased to
match the reserve amount. If the reserve 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
reservation is used to preallocate space for a file.
The a_flags element is used to indicate the type of reservation
required. The choices are:
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
vxfsio(7) vxfsio(7)
VX_ALIGN [Toc] [Back]
Align all new extents on an ext_size boundary relative
to the starting block of an allocation unit. If
VX_CONTIGUOUS is also set, the single extent allocated
during this invocation is not subject to the alignment
restriction.
VX_CHGSIZE [Toc] [Back]
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.
VX_CONTIGUOUS [Toc] [Back]
The reservation must be allocated contiguously (as a
single extent). ext_size 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 happen. VX_CHGSIZE 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.
VX_NOEXTEND [Toc] [Back]
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.
VX_NORESERVE [Toc] [Back]
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.
VX_TRIM [Toc] [Back]
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
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
vxfsio(7) vxfsio(7)
information. Extent information only applies to regular files.
Only one set of extent information is kept per file. Only the
VX_ALIGN and VX_NOEXTEND allocation flags are persistent
attributes of the file. Other allocation flags may have
persistent effects, but are not visible as allocation flags.
VX_ALIGN, VX_NOEXTEND, and VX_TRIM are the only flags visible
through the VX_GETEXT ioctl.
The VX_SETEXT ioctl returns a zero if the extent information is
successfully set. If the operation fails, the return value is -1
and the external variable errno is a general DIAGNOSTIC.
VX_THAW [Toc] [Back]
Unblock a file system that has been frozen by a VX_FREEZE
operation. The argument arg should be NULL. The process that is
to issue a VX_THAW 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 VX_THAW ioctl returns a zero if the file system is
successfully unfrozen. If the operation fails, the return value
is -1 and the external variable errno is a general DIAGNOSTIC or
one of the diagnostics listed in the DIAGNOSTICS section.
EXAMPLES [Toc] [Back]
The following example shows how application code can use VX_GETFSOPT
to find out if a JFS file system was mounted with the -o delaylog
option:
int arg = 0;
int fd;
ioctl(fd, VX_GETFSOPT, &arg);
if (arg & VX_FSO_DELAYLOG) {
printf("FS mounted with delaylog option!\n");
}
DIAGNOSTICS [Toc] [Back]
Operation failures can return any of the following values in errno:
EACCESS The calling process does not have write access to the
file specified by fildes.
EAGAIN The file system is not currently frozen.
EBADF The fildes argument is not a valid file descriptor open
for writing.
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
vxfsio(7) vxfsio(7)
EFAULT An address specified by an argument is invalid.
EFBIG An attempt was made to reserve space larger than the
maximum file size limit for this process.
EINVAL The command or argument is invalid.
EIO An I/O error occurred while attempting to perform the
operation.
ENODEV The file specified by fildes is not the root directory
of a vxfs file system.
ENOSPC Requested space could not be obtained.
EPERM The process does not have appropriate privilege.
EROFS The file system is mounted read-only.
ETIMEDOUT The VX_FREEZE timeout expired before this call.
SEE ALSO [Toc] [Back]
fsadm_vxfs(1M), mount_vxfs(1M), vxtunefs(1M), fcntl(2), getrlimit(2),
ioctl(2), ulimit(2).
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003 [ Back ] |
