unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



 vxtrace(7)			  VxVM 3.5			  vxtrace(7)
				 1 Jun 2002



 NAME
      vxtrace - VERITAS Volume Manager I/O Tracing Device

 SYNOPSIS
      /dev/vx/trace

 DESCRIPTION
      The vxtrace device implements the VERITAS Volume Manager (VxVM) I/O
      tracing and the error tracing.  An I/O tracing interface is available
      that users or processes can use to get a trace of I/Os for specified
      sets of kernel objects.  Each separate user of the I/O tracing
      interface can specify the set of desired trace data independent of all
      other users.  I/O events include regular read and write operations,
      special I/O operations (ioctls), as well as special recovery
      operations (for example, recovery reads).	 A special tracing mechanism
      exists for getting error trace data.  The error tracing mechanism is
      independent of any I/O tracing and is always enabled for all pertinent
      kernel I/O objects.  It is possible for a process to get both a set of
      saved errors and to wait for new errors.

 IOCTLS
      The format for calling each ioctl command is:

	   #include <&lt&lt&lt;sys/types.h>&gt&gt&gt;
	   #include <&lt&lt&lt;vxvm/voltrace.h>&gt&gt&gt;
	   struct tag arg;
	   int ioctl (int fd, int cmd, struct  tag arg);

      The first argument fd is a file descriptor which is returned from
      opening the /dev/vx/trace device.	 Each tracing device opened is a
      cloned device which can be used as a private kernel trace channel.
      The value of cmd is the ioctl command code, and arg is usually a
      pointer to a structure containing the arguments that need to be passed
      to the kernel.

      The return value for all these ioctls is 0 if the command was
      successful, and -1 if it was rejected.  If the return value is -1,
      errno is set to indicate the cause of the error.

      The following ioctl commands are supported:

      VOLIOT_ERROR_TRACE_INIT
	   This command accepts no argument.  The VOLIOT_ERROR_TRACE ioctl
	   initializes a kernel trace channel to return error trace data.
	   The trace channel will be initialized to return any previously
	   accumulated error trace data that has not yet been discarded. The
	   accumulated trace data can be skipped by issuing VOLIOT_DISCARD
	   on the channel.  This call can be issued on a trace channel that
	   was previously initialized either for error tracing or for
	   regular I/O tracing. In this case, the channel is effectively
	   closed down and then reinitialized as described above.  To get



				    - 1 -	  Formatted:  August 2, 2006






 vxtrace(7)			  VxVM 3.5			  vxtrace(7)
				 1 Jun 2002



	   the error trace data, issue the read(2) system call. The error
	   trace data consists of a set of variable length trace event
	   records. The first byte of each record indicates the length, in
	   bytes, of the entire record (including the length byte), the
	   second byte indicates the type of the entry (which can be used to
	   determine the format of the entry).	Each call to read() returns
	   an integral number of trace event records, not to exceed the
	   number of bytes requested in the read() call; the return value
	   from read() will be adjusted to the number of bytes of trace data
	   actually returned. If the O_NONBLOCK flag is set on the trace
	   channel, and no trace data is available, EAGAIN will be returned;
	   otherwise, the read will block interruptibly until at least one
	   trace record is available. When some trace data is available, the
	   available unread trace records will be returned, up to the limit
	   specified in the call to read(). If more trace records are
	   available, subsequent reads will return those records.

      VOLIOT_IO_TRACE_INIT
	   The VOLIOT_IO_TRACE_INIT ioctl initializes a kernel trace channel
	   to return I/O trace data.  This command accepts bufsize as the
	   argument.  Initially, no objects are selected for I/O tracing. To
	   select objects to trace, issue the VOLIOT_IO_TRACE ioctl. The
	   bufsize argument specifies the kernel buffer size to use for
	   gathering events. A larger size reduces the chance that events
	   are lost due to scheduling delays in the event reading process. A
	   bufsize value of 0 requests a default size which is considered
	   reasonable for the system. The value of bufsize will be silently
	   truncated to a maximum value to avoid extreme use of system
	   resources. A bufsize value of (size_t)-1 will yield the maximum
	   buffer size.

      VOLIOT_IO_TRACE,VOLIOT_IO_UNTRACE
	   The VOLIOT_IO_TRACE and VOLIOT_IO_UNTRACE ioctls enable and
	   disable, respectively, I/O tracing for particular sets of objects
	   on an I/O tracing channel.  They both accept a voliot_want_list
	   structure tracelist as the argument.	 The tracelist argument
	   specifies object sets.  The voliot_want_list structure specifies
	   an array of desired object sets. Each object set is identified by
	   a union of structures (the voliot_want_set union), each
	   representing different types of object sets.	 See the declaration
	   of these structures in voltrace.h for more detail.

 FILES
      /dev/vx/trace

 SEE ALSO
      vxintro(1M), vxtrace(1M), vxvol(1M) ioctl(2), read(2), vxconfig(7),
      vxiod(7)






				    - 2 -	  Formatted:  August 2, 2006