vxfsio(7) (VxFS) vxfsio(7)
NAME
vxfsio - Veritas File System control functions (VxFS)
SYNOPSIS
#include <sys/types.h>
#include <sys/fs/vxioctl.h>
int ioctl(int fildes, int cmd, arg);
DESCRIPTION
The ioctl(2) enhancements for VxFS provide for extended control over
open files.
The argument fildes is an open filedescriptor.
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/vxioctl.h> header file.
The enhancements available are:
VXSETCACHE
Set caching advisories. These advisories allow an application to
indicate to the file system which forms of caching would be most
advantageous. The values for arg are such that multiple
advisories may be set by combining values with logical OR opera-
tions. The possible values for arg are:
VXRANDOM Indicates that the file is being accessed randomly.
Read-ahead should not be performed.
VXSEQ Indicates that the file is being accessed sequen-
tially. Maximum read-ahead should be performed.
VXDIRECT 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 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 boun-
dary.
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.
VXNOREUSE Indicates that buffered data does not need to be
retained in anticipation of further use by the
application.
Page 1 Reliant UNIX 5.44 Printed 11/98
vxfsio(7) (VxFS) vxfsio(7)
VXDSYNC 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.
Only one of VXRANDOM, VXSEQ, or VXDIRECT may be
specified. The VXNOREUSE and VXDSYNC options may
not be used in conjunction with VXDIRECT. The cach-
ing advisories for a file are maintained on a per-
file basis. Changes made to the advisories by a pro-
cess affect I/O operations by all processes
currently accessing the file.
The VXSETCACHE 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 such
as the following:
EINVAL The file specified by fildes is not a regular file,
or the combination of advisories is invalid.
VXGETCACHE
Get caching advisories in effect for the file. The argument arg
should be a pointer to to an int.
The VXGETCACHE ioctl returns a 0 if the caching advisories are
successfully obtained. If the operation fails, the return value
is -1 and the external variable errno will be a general diagnos-
tic such as the following:
EINVAL The file specified by fildes is not a regular file.
Page 2 Reliant UNIX 5.44 Printed 11/98
vxfsio(7) (VxFS) vxfsio(7)
VXSETEXT
Set extent information. Set the extent information according to
the parameters specified by arg. The argument arg points to a
structure of type vxext defined in <sys/fs/vxioctl.h>, which
contains the following members:
offt extsize; /* extent size */
offt reserve; /* space reservation */
int aflags; /* allocation flags */
The extsize 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 con-
tains indirect blocks have no effect unless all current indirect
blocks are freed via file truncation and/or reservation dealloca-
tion.
The reserve element is used to set the amount of space preallo-
cated 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 processes ulimit(2). Reservation of
space for existing sparse files will not cause blocks to be allo-
cated to fill in the holes, but will only allocate blocks after
the end of the file. Thus, it is possible to have a larger reser-
vation for a file than blocks in the file.
The reservation amount is independent of file size since reserva-
tion is used to preallocate space for a file. The aflags element
is used to indicate the type of reservation required. The choices
are:
VXNOEXTEND The file may not be extended once the current reser-
vation is exceeded. The reservation may be increased,
if necessary, by another invocation of the ioctl, but
the file will not be extended automatically.
VXTRIM 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.
VXCONTIGUOUS
The reservation must be allocated contiguously (as a
single extent). extsize will become the fixed extent
size for subsequent allocations, but has no affect on
this one. The reservation will fail if the file has
Page 3 Reliant UNIX 5.44 Printed 11/98
vxfsio(7) (VxFS) vxfsio(7)
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.
VXALIGN Align all new extents on an extsize boundary rela-
tive to the starting block of an allocation unit. If
VXCONTIGUOUS is set, the single extent allocated
during this invocation is not subject to the align-
ment restriction.
VXNORESERVE
The reservation is to be made as a nonpersistent
allocation to the file. The on-disk inode will not
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.
VXCHGSIZE The reservation is to be immediately incorporated
into the file. The file's on-disk inode is updated to
with size and block count information that is
increased to include the reserved space. Unlike an
fcntl FFREESP operation which "truncates-up" [see
fcntl(2)], the space included in the file is not ini-
tialized.
This operation is restricted to users with appropri-
ate privilege (root).
Write permission to a file is required to set extent information,
but any process which can open the file can get the extent infor-
mation. Extent information only applies to regular files. Only
one set of extent information is kept per file. Except in those
cases noted above as non-persistent, the extent information
becomes part of the on-disk inode information and, thus, persists
across reboots. The conditional allocations mentioned above are
the only exceptions here (see VXNORESERVE).
Page 4 Reliant UNIX 5.44 Printed 11/98
vxfsio(7) (VxFS) vxfsio(7)
The VXSETEXT ioctl returns a 0 if the extent information is suc-
cessfully set. If the operation fails, the return value is -1 and
the external variable errno will be a general diagnostic or one
of the following:
EINVAL The file specified by fildes is not a regular file,
or the requested extent information is invalid.
EACCESS The calling process does not have write access to the
file specified by fildes.
EFBIG Attempting to reserve space larger than the maximum
file size limit for this process.
VXGETEXT
Get extent information. Return the extent information associated
with fildes. The argument arg points to a structure of type
vxext, as defined in <sys/fs/vxioctl.h>.
The VXGETEXT ioctl returns a 0 if the extent information is suc-
cessfully obtained. If the operation fails, the return value is
-1 and the external variable errno will be a general diagnostic
or the following:
EINVAL The file specified by fildes is not a regular file.
VXGETFSOPT
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:
VXFSOBLKCLEAR
Indicates that all newly allocated blocks will be
guaranteed to contain all zeros.
VXFSOCACHECLOSESYNC
Indicates that any nonlogged changes to the inode or
data will be flushed to disk when the file is closed.
VXFSOCACHEDIRECT
Indicates that any nonsynchronous I/O will be handled
as if the VXDIRECT 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.
Page 5 Reliant UNIX 5.44 Printed 11/98
vxfsio(7) (VxFS) vxfsio(7)
VXFSOCACHEDSYNC
Indicates that any writes that do not have either
OSYNC or the VXDIRECT advisory set will be handled
as if the VXDSYNC advisory had been set on the file.
Also, any nonlogged changes to the inode or data will
be flushed to disk when the file is closed.
VXFSONODATAINLOG
Indicates that intent logging of user data for syn-
chronous writes is disabled.
VXFSONOLOG
Indicates that intent logging of structural changes
to the file system is disabled.
VXFSOOSYNCCLOSESYNC
Indicates that any non-logged changes to the inode or
data will be flushed to disk when a file accessed
with OSYNC is closed.
VXFSOOSYNCDIRECT
Indicates that any OSYNC I/O will be handled as if
the VXDIRECT 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 OSYNC is closed.
VXFSOOSYNCDSYNC
Indicates that any OSYNC writes will be handled as
if the VXDSYNC 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 OSYNC is closed.
VXFSOSNAPPED
Indicates that a snapshot backup is in progress on
the file system.
VXFSOSNAPSHOT
Indicates that this file system is a snapshot backup
of another file system.
The VXGETFSOPT 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 diagnos-
tic or the following:
EINVAL The file specified by fildes is not a regular file.
Page 6 Reliant UNIX 5.44 Printed 11/98
vxfsio(7) (VxFS) vxfsio(7)
VXFREEZE
Sync, then freeze the file system. Once frozen, all further
operations against the file system block until a VXTHAW opera-
tion is received. The argument arg is a timeout value expressed
in seconds. If a VXTHAW operation is not received within the
specified timeout interval, the file system will perform a
VXTHAW operation automatically.
This command may only be used by a user with appropriate privi-
lege on the root directory of the file system.
The VXFREEZE ioctl returns a 0 if the file system is success-
fully frozen. If the operation fails, the return value is -1 and
the external variable errno will be a general diagnostic or the
following:
EINVAL The timeout value specified by arg is less than 1.
VXTHAW
Unblock a file system which has been frozen by a VXFREEZE opera-
tion. The argument arg should be NULL. The process which is to
issue a VXTHAW 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 privi-
lege on the root directory of the file system.
The VXTHAW 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 will be a general diagnostic or one of
the following:
EAGAIN The file system is not currently frozen.
VXEXPAND
Expand the size of the file system. The argument arg specifies
the desired size, expressed in file system blocks.
This command may only be used by a user with appropriate privi-
lege on the root directory of the file system.
The VXEXPAND ioctl returns a 0 if the file system is success-
fully expanded. If the operation fails, the return value is -1
and the external variable errno will be a general diagnostic or
one of the following:
Page 7 Reliant UNIX 5.44 Printed 11/98
vxfsio(7) (VxFS) vxfsio(7)
EROFS The file system is mounted read-only.
EINVAL The requested file system size is not larger than the
current file system size, or is larger than the max-
imum supported file system size.
VXDIRSORT
Sort and compress a set of directory blocks. The argument arg
points to a structure of type dirsort as defined in
<sys/fs/vxioctl.h>, which contains the following members:
#define VXDIRSORTBUFS 2 /* number of directory buffers */
inot dirinode; /* inode number of directory */
daddrt diroff[VXDIRSORTBUFS]; /* block offset in directory */
daddrt dirbno[VXDIRSORTBUFS]; /* original block numbers */
daddrt diribuf[VXDIRSORTBUFS]; /* original block contents */
daddrt dirobuf[VXDIRSORTBUFS]; /* new block contents */
daddrt dirolen[VXDIRSORTBUFS]; /* new length of blocks */
The directory inode specified by dirinode will be reorganized.
The blocks dirblkoff and dirblkoff + 1 within the directory
will be read. If the directory entries in those blocks are ident-
ical to the directory entries in dirbuf, then the directory
entries will be reordered to match the dirbuf.
If the reordered directory can fit in immediate data, then it
will be placed in the immediate data area and the directory block
will be released. If the reordering leaves the last block of the
directory free, then the block will be released.
This command may only be used by a user with appropriate privi-
lege on the root directory of the file system.
The VXDIRSORT 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 or
one of the following:
EINVAL A member of the dirsort structure is invalid.
ENOTDIR The file specified by dirinode is not a directory.
EBUSY The current directory contents do not match those
specified in the dirsort structure.
Page 8 Reliant UNIX 5.44 Printed 11/98
vxfsio(7) (VxFS) vxfsio(7)
VXEXTREORG
Reorganize a set of extents in a file. The argument arg points to
a structure of type extreorg, as defined in <sys/fs/vxioctl.h>,
which contains the following members:
inot extinum; /* inode number */
long extigen; /* generation count of file */
offt extisize; /* size of file in blocks */
offt extiblocks; /* blocks held by file */
offt extoffset; /* offset in file to reallocate from */
offt extsize; /* number of blocks to reallocate */
struct extalloc extalloc[5]; /* type of reallocation to do */
struct dinode *extinode; /* pointer to inode */
Attempt to reallocate extents in the file specified by extinum.
The extigen, extisize, and extiblocks fields are used to vali-
date the inode. If these fields are nonzero, and they do not
match the values in the inode, then the reorganization will fail.
The extoffset and extsize fields define an area of the file.
The ioctl will attempt to allocate new extents for that area. If
successful, then the file data will be copied to the new extents,
and the old extents for that area will be released. This can be
used to move files to a different location, or to combine small
extents to reduce fragmentation.
The extalloc array of extalloc structures determines how the
reallocation will occur. The extalloc structure is defined in
<sys/fs/vxioctl.h>; it contains the following members:
long extcmd; /* type of reallocation */
long extflag; /* flag indicating search direction */
daddrt extstart; /* starting block for search */
daddrt extend; /* ending block for search */
long extnextents; /* max number of extents to allocate */
The extcmd field determines the type of search to make. The pos-
sible values are:
EXTSEARCH Search the area from extstart to extend for one
extent of extsize blocks. The extflag field con-
trols the direction of the search. If extflag is
EXTFORWARD, then the search runs from extstart to
extend. If the extflag is EXTBACKWARD, then the
search runs from extend to extstart. If a search
hits the end of the file system, then it wraps around
to the other end.
EXTPREALLOC
Use the kernel's space preallocation algorithm to
Page 9 Reliant UNIX 5.44 Printed 11/98
vxfsio(7) (VxFS) vxfsio(7)
allocate extents totaling extsize blocks. If more
than extnextents are required, then fail the
attempt.
Any extents allocated by the reallocation must meet all the files
restrictions on extent size, alignment, and contiguity.
The extinode field is a pointer to a disk inode structure. If it
is not NULL, then on a successful reallocation, the new inode
will be copied into the specified dinode structure, as defined in
<sys/fs/vxinode.h>.
This command may only be used by a user with appropriate privi-
lege on the root directory of the file system.
The VXEXTREORG ioctl returns a 0 if all of the reallocation
attempts failed. If a reallocation occurred, then the return
value is 1 plus the index of the successful reallocation command
in the extalloc array. If the operation fails, the return value
is -1 and the external variable errno will be a general diagnos-
tic or the following:
EINVAL The file specified by fildes is not a regular file.
The file specified by fildes has allocated indirect
extents. The file size, block allocation, or genera-
tion count does not match that specified in the
extreorg structure.
DIAGNOSTICS
The following values are returned in errno upon operation failure:
EPERM The process does not have appropriate privilege.
ENODEV The file specified by fildes is not the root directory of
an Veritas 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.
SEE ALSO
ioctl(2), getrlimit(2), ulimit(2).
Page 10 Reliant UNIX 5.44 Printed 11/98