vxfsio(7) (VXFS) vxfsio(7)
NAME
vxfsio - vxfs file system control functions
SYNOPSIS
#include <sys/types.h>
#include <sys/fs/vx_ioctl.h>
int ioctl (int fildes, int cmd, arg);
DESCRIPTION
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.
The enhancements available are:
VX_SETCACHE
Set caching advisories. These advisories allow an
application to indicate to the file system which forms
of caching would be most advantageous.
NOTE: VX_SETCACHE is available with the VxFS Advanced
package 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_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_DIRECT
Indicates that data associated with read and write
operations is to be transferred directly to or
from the user supplied buffer, without being
Copyright 1994 Novell, Inc. Page 1
vxfsio(7) (VXFS) vxfsio(7)
cached. When this options 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 page boundary.
If an I/O request fails to meet alignment
criteria, or the file is currently being accessed
for mapped I/O, the I/O request will be performed
as a data synchronous I/O operation.
VX_NOREUSE
Indicates that buffered data does not need to be
retained in anticipation of further use by the
application.
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.
Only one of VX_RANDOM, VX_SEQ, or VX_DIRECT may be
specified. The VX_NOREUSE and VX_DSYNC options may not
be used in conjunction with VX_DIRECT. The caching
advisories for a file are maintained on a per-file
basis. Changes made to the advisories by a process
affect I/O operations by all processes currently
accessing the file.
The VX_SETCACHE ioctl returns a 0 if the caching
advisories are successfully set. If the operation
fails, the return value is -1 and the external variable
errno will be a general DIAGNOSTIC.
VX_GETCACHE
Get caching advisories in effect for the file. The
argument arg should be a pointer to to an int.
The VX_GETCACHE ioctl returns a 0 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 will be a
Copyright 1994 Novell, Inc. Page 2
vxfsio(7) (VXFS) vxfsio(7)
general DIAGNOSTIC.
VX_SETEXT
Set extent information.
NOTE: VX_SETEXT is available with the VxFS Advanced
package 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,
which contains the following members:
off_t ext_size; /* extent size */
off_t reserve; /* space reservation */
int a_flags; /* allocation flags */
The ext_size element is used to request a fixed extent
size, in blocks, for the file. If a fixed extent size
is not required, zero should be used 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 is used to set the amount of space
preallocated to the file. 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 will not be
reduced to less than the current file size.
File reservation cannot be increased beyond the
ulimit(2) of the requesting process. However, an
existing reservation will not be trimmed to the
requesting process's ulimit(2). Reservation of space
for existing sparse files will not cause blocks to be
allocated to fill in the holes, but will only allocate
blocks after the end of the file. Thus, its 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.
Copyright 1994 Novell, Inc. Page 3
vxfsio(7) (VXFS) vxfsio(7)
The a_flags element is used to indicate the type of
reservation required. The choices are:
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 will not be automatically
extended.
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.
VX_CONTIGUOUS
The reservation must be allocated contiguously (as
a single extent). ext_size will become the fixed
extent size for subsequent allocations, but has no
affect on this one. The reservation will fail 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
will not happen.
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_NORESERVE
The reservation is to be made as a non-persistent
allocation to the file. The on-disk inode will
not be updated with the reservation information so
that the reservation will 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_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
Copyright 1994 Novell, Inc. Page 4
vxfsio(7) (VXFS) vxfsio(7)
that is increased to include the reserved space.
Unlike an fcntl F_FREESP operation which
``truncates-up'' [see fcntl(2)], the space
included in the file is not initialized. This
operation is restricted to users with appropriate
privileges.
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.
The VX_SETEXT ioctl returns a 0 if the extent
information is successfully set. If the operation
fails, the return value is -1 and the external variable
errno will be 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 0 if the extent
information is successfully obtained. If the operation
fails, the return value is -1 and the external variable
errno will be a general DIAGNOSTIC.
VX_GETFSOPT
Get file system options. The argument arg should be a
pointer to 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 will be
guaranteed to contain all zeros.
VX_FSO_CACHE_CLOSESYNC
Indicates that any non-logged changes to the inode
or data will be flushed to disk when the file is
Copyright 1994 Novell, Inc. Page 5
vxfsio(7) (VXFS) vxfsio(7)
closed.
VX_FSO_CACHE_DIRECT
Indicates that any non-synchronous I/O will be
handled as if the VX_DIRECT cache advisory had
been set on the file. Also, any non-logged
changes to the inode or data will be flushed to
disk when the file is closed.
VX_FSO_CACHE_DSYNC
Indicates that any writes that don't have either
O_SYNC or the VX_DIRECT advisory set will be
handled as if the VX_DSYNC advisory had been set
on the file. Also, any non-logged changes to the
inode or data will be flushed to disk when the
file is closed.
VX_FSO_NODATAINLOG
Indicates that intent logging of user data for
synchronous writes is disabled.
VX_FSO_NOLOG
Indicates that intent logging of structural
changes to the file system is disabled.
VX_FSO_OSYNC_CLOSESYNC
Indicates that any non-logged changes to the inode
or data will be flushed to disk when a file
accessed with O_SYNC is closed.
VX_FSO_OSYNC_DIRECT
Indicates that any O_SYNC I/O will be 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 will be flushed to disk when a
file accessed with O_SYNC is closed.
VX_FSO_OSYNC_DSYNC
Indicates that any O_SYNC writes will be 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 will be flushed to disk when a
file accessed with O_SYNC is closed.
Copyright 1994 Novell, Inc. Page 6
vxfsio(7) (VXFS) vxfsio(7)
VX_FSO_SNAPPED
Indicates that a snapshot backup is in progress on
the file system.
VX_FSO_SNAPSHOT
Indicates that this file system is a snapshot
backup of another file system.
VX_FSO_VJFS
Indicates that this is not the VxFS Advanced
package.
The VX_GETFSOPT ioctl returns a 0 if the file system
options are successfully obtained. If the operation
fails, the return value is -1 and the external variable
errno will be a general DIAGNOSTIC.
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 will perform a VX_THAW
operation automatically.
This command may only be used by a user with appropriate
privilege, on the root directory of the file system.
The VX_FREEZE ioctl returns a 0 if the file system is
successfully frozen. If the operation fails, the return
value is -1 and the external variable errno will be 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.
This command may only be used by a user with appropriate
privilege, on the root directory of the file system.
Copyright 1994 Novell, Inc. Page 7
vxfsio(7) (VXFS) vxfsio(7)
The VX_THAW ioctl returns a 0 if the file system is
successfully unfrozen. If the operation fails, the
return value is -1 and the external variable errno is
set to identify the reason for the failure.
DIAGNOSTICS
The following values are returned in errno upon operation
failures:
EACCESS The calling process does not have write access
to the file specified by fildes.
EAGAIN The file system is not currently frozen.
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.
EPERM The process does not have appropriate privilege.
ENODEV The file specified by fildes is not the root
directory of a vxfs file system.
EROFS The file system is mounted read-only.
EIO An I/O error occurred while attempting to
perform the operation.
ENOSPC Requested space could not be obtained.
EFAULT An address specified by an argument is invalid.
NOTES
Under certain circumstances, fsadm may reorganize the extent
map of a file in such a way as to make it less contiguous.
However, it will not change the geometry of a file that has a
fixed extent size.
REFERENCES
getrlimit(2), ioctl(2), ulimit(2)
Copyright 1994 Novell, Inc. Page 8