Home > Veritas Storage Foundation™ Volume Manager Manual Pages
Table of contents
vxtrace - Veritas Volume Manager I/O Tracing Device
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
The format for calling each ioctl command is:
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,
is set to indicate the cause of the error.
The following ioctl commands are supported:
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 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.
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.
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.
Last updated: 28 Jul 2003
Copyright ©2009 Symantec Corporation
All rights reserved.