vxtrace(7)						 Miscellaneous Information Manual						vxtrace(7)

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  inter-
       face  can specify the set of desired trace data independent of all other users.	I/O events include regular read and write operations, spe-
       cial 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 <sys/types.h>
	      #include <vxvm/voltrace.h>
	      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  accumu-
	    lated  trace data can be skipped by issuing VOLIOT_DISCARD on the channel.	This call can be issued on a trace channel that was previ-
	    ously 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 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 argu-
	    ment.   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)

VxVM 5.0.31.1							    24 Mar 2008 							vxtrace(7)