vxfsio(HW)

Synopsis

#include <sys/types.h> 
#include <sys/fs/vx_ioctl.h> 
int ioctl (int fildes, int cmd, arg); 

Description

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 only with the VxFS Advanced feature set.

---

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 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 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.

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 has been 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 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 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 general diagnostic.

VX_SETEXT

Set extent information.

---

NOTE: VX_SETEXT is available only with the VxFS Advanced feature set.

---

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 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 (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 will not be reduced to less than the current file size.

File reservation cannot be increased beyond the ulimit(S) of the requesting process. However, an existing reservation will not be trimmed to the requesting process's ulimit(S). 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.

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 that is increased to include the reserved space. Unlike an fcntl F_FREESP operation which ``truncates-up'' (see fcntl(S)), 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. VX_ALIGN, VX_NOEXTEND, and VX_IETRIM are the only flags visible through the VX_GETEXT ioctl.

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_NOLOG

Indicates that intent logging of structural changes to the file system is disabled.

VX_FSO_NODATAINLOG

Indicates that intent logging of user data for synchronous writes is disabled.

VX_FSO_DELAYLOG

Indicates that some system calls may return before the intent log is written.

VX_FSO_TMPLOG

Indicates that the intent log is almost always delayed.

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 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_CACHE_TMPCACHE

Disables delayed extending writes. Non-logged changes to the inode or data will not be flushed to disk when the file is closed.

VX_FSO_CACHE_UNBUFFERED

Indicates that any non-synchronous I/O will be handled as if the VX_UNBUFFERED 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_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.

VX_FSO_OSYNC_DELAY

Indicates that any O_SYNC writes will be delayed rather than to take effect immediately. No special action is taken when a file is closed.

VX_FSO_OSYNC_UNBUFFERED

Indicates that any O_SYNC I/O will be handled as if the VX_UNBUFFERED cache advisory had been set on the file. 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_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 feature set.

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.

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 will be a general diagnostic or one of the following:

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 0 if the parameters are successfully obtained. If the operation fails, the return value is -1 and the external variable errno will be 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 will cause 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 will fit in the cache, then using unbuffered I/O will avoid throwing a lot of useful data out of the cache and it will avoid a lot of CPU overhead. The vxtunefs(ADM) manual page has more information on discovered direct I/O.

Diagnostics

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.

References

Notices