 |
» |
|
|
|
NAMEvxfsio — VxFS file system control functions SYNOPSIS#include <sys/types.h>
#include <sys/fs/vx_ioctl.h>
int ioctl(int fildes, int cmd, ... /* arg */); DESCRIPTIONThe
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. NotesIn 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 FlagsThe 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
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
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
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 the
vxtunefs(1M)
manual page for more information on discovered direct I/O.
- VX_GETCACHE
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
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
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
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
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
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
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)). - VX_FSO_CACHE_TMPCACHE
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
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
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
Indicates that intent logging
of user data for synchronous writes
is disabled.
(See the
nodatainlog
mount option of
mount_vxfs(1M)). - VX_FSO_NOLOG
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
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
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
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
Indicates that any
O_SYNC
writes is handled as if the
VX_DSYNC
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=dsync
mount option of
mount_vxfs(1M)). - VX_FSO_OSYNC_UNBUFFERED
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
Indicates that a snapshot backup
of this file system is being maintained. - VX_FSO_SNAPSHOT
Indicates that this file system
is a snapshot backup
of another file system. - VX_FSO_TMPLOG
Indicates that the intent log is almost always delayed.
(See the
tmplog
mount option of
mount_vxfs(1M)). - VX_FSO_VJFS
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
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
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. - VX_DSYNC
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
Indicates that buffered data
does not need to be retained
in anticipation of further use
by the application. - VX_RANDOM
Indicates that the file is being accessed randomly.
Read-ahead should not be performed. - VX_SEQ
Indicates that the file is being accessed sequentially.
Maximum read-ahead should be performed. - VX_UNBUFFERED
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. 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
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:
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:
- VX_ALIGN
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
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
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
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
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
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 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
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.
EXAMPLESThe 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");
} DIAGNOSTICSOperation 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. - 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.
|
