unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 vxfsio(7)							   vxfsio(7)




 NAME
      vxfsio - VxFS file system control functions

 SYNOPSIS
      #include <&lt&lt&lt;sys/types.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/fs/vx_ioctl.h>&gt&gt&gt;

      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 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_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 word boundary.




 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 vxfsio(7)							   vxfsio(7)




		     If an I/O request fails to meet alignment criteria, 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 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_GETCACHE
	   Get caching advisories in effect for the file.  The argument arg
	   should be a pointer to an int.




 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 vxfsio(7)							   vxfsio(7)




	   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_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:

		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(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, 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_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



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 vxfsio(7)							   vxfsio(7)




		     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.  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_TRIM are the only flags visible
	   through the VX_GETEXT ioctl.





 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 vxfsio(7)							   vxfsio(7)




	   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 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 zero 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
	   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.  (See the blkclear
		     mount option of mount_vxfs(1M)).

		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.
		     (See the mincache=closesync mount option of
		     mount_vxfs(1M)).

		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.
		     (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 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.  (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 will
		     not be flushed to disk when the file is closed.  (See



 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 vxfsio(7)							   vxfsio(7)




		     the mincache=tmpcache mount option of mount_vxfs(1M)).

		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.
		     (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 will be 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 will be 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 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.	(See the convosync=direct mount
		     option of mount_vxfs(1M)).

		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.	(See the convosync=dsync mount
		     option of mount_vxfs(1M)).



 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 vxfsio(7)							   vxfsio(7)




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

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



 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 vxfsio(7)							   vxfsio(7)




	   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.

      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 ty 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 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.  See the vxtunefs(1M) manual page for more information
	   on discovered direct I/O.



 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






 vxfsio(7)							   vxfsio(7)




 EXAMPLES
      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:

		   struct vx_genioctl	   ioc;
		   int			   arg = 0;
		   int			   fd;
		   ioc.ioc_cmd = VX_GETFSOPT;
		   ioc.ioc_up = &&amp&amp&amp;arg;
		   ioctl(fd, VX_ADMIN_IOCTL, &&amp&amp&amp;ioc);
		   if (arg &&amp&amp&amp; VX_FSO_DELAYLOG) {
			printf("FS mounted with delaylog option!\n");
		   }

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

      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.

 NOTES
      In some cases, 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.

 SEE ALSO
      fsadm_vxfs(1M), mount_vxfs(1M), getrlimit(2), ioctl(2), ulimit(2).





 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000