<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Transitional//EN">
<HTML>
<HEAD>
  <!--
    *************************************************************************************
    * Copyright (c) 2005 VERITAS Software Corporation. All rights reserved. *

      For third-party license citations, please see the bottom of this file.
    *************************************************************************************
  -->
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="TEMPLATEBASE" content="DocCD Manual Pages 1.4">
<meta name="LASTUPDATED" content="06/13/05 11:54:21">
<meta name="PRODUCTNAME" content="VERITAS Software Documentation">
<meta name="FILENAME" content="vxtrace.fm">
     
<title>vxtrace</title>

</HEAD>

<BODY bgcolor="#FFFFFF" link="#000066" vlink="#0000ff" marginheight="0" topmargin="0">
<basefont=1>

<a name="427612"></a>

<div align="left">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
 <tr>
   <td height="2" border="0" cellspacing="0" cellpadding="0" colspan="2" bgcolor="#000000">
   </td>
 </tr>
 <tr>
   <td height="15" width="50%" border="0" cellspacing="0" cellpadding="0" bgcolor="#cccccc">
    <img src="images/vxsymbol.gif" height="20" width="31" border="0" cellspacing="0" cellpadding="0" align="left">
     
     
   </td>
   <td align="right" width="50%" bgcolor="#cccccc">

<!-- Header Breadcrumbs -->
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="-2">&lt;&nbsp;<a href="vxiod_vxvm_manpages98_427949.html" title="Previous - vxiod">Previous</a>&nbsp;&nbsp;</font>
   </td>
 </tr>

 <tr>
  <td bgcolor="#CCCCCC" colspan="2" height="15" align="right">
  <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="1">Product:  
<a href="vxvm_manpages_splashpage_docCD_vxvm_manpages1_103036.vxhd" title="Volume Manager Manual Pages for Storage Foundation title page ">Volume Manager Manual Pages for Storage Foundation</a>
  &nbsp;&nbsp;
  </font>
  </td>
 </tr>
 <tr>
  <td bgcolor="#CCCCCC" colspan="2" height="15" align="right">
  <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="1">Manual:  
<a href="man7_titlepage_docCD_vxvm_manpages92_73700.vxhd" title="Miscellaneous (7) title page ">Miscellaneous (7)</a>
  &nbsp;&nbsp;
  </font>
  </td>
 </tr>


</table>
</div>

<div align="left">
 <table border="0" width="100%" bgcolor="#FFFFFF">
  <tr>
   <td width="100%" valign="top" bgcolor="#FFFFFF">

<!-- Start Main Topic Content -->
        <a name="startcontent"></a>
	
<h2><font face="Arial, Helvetica, Geneva, sansserif, sans serif, Verdana" size="3" color="#000000"><a name="426876"></a>vxtrace</font>
</h2>

        

<h3><font face="Arial, Helvetica, Geneva, sansserif, sans serif, Verdana" size="2" color="#000000">
<a name="426899"></a> NAME</font>
</h3>
<p>
<a name="426904"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2">vxtrace - VERITAS Volume Manager I/O Tracing Device </font>
</p>

<h3><font face="Arial, Helvetica, Geneva, sansserif, sans serif, Verdana" size="2" color="#000000">
<a name="426907"></a> SYNOPSIS</font>
</h3>
<br>
<font face="Courier, Courier New, sansserif, sans serif" size="2"><a name="426912"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>/dev/vx/trace </b></font>
</font>

<h3><font face="Arial, Helvetica, Geneva, sansserif, sans serif, Verdana" size="2" color="#000000">
<a name="426915"></a> DESCRIPTION</font>
</h3>
<p>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="426920"></a>The <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>vxtrace </b></font>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. </font>
</p>


<h3><font face="Arial, Helvetica, Geneva, sansserif, sans serif, Verdana" size="2" color="#000000">
<a name="427049"></a> IOCTLS</font>
</h3>
<p>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="427054"></a>The format for calling each ioctl command is: </font>
</p>

<br>
<font face="Courier New, Courier, sansserif, sans serif" size="2"><a name="427063"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>#include&nbsp;&lt;sys/types.h&gt;</b></font>
</font>
<br>
<font face="Courier New, Courier, sansserif, sans serif" size="2"><a name="427071"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>#include&nbsp;&lt;vxvm/voltrace.h&gt;</b></font>
</font>
<br>
<font face="Courier New, Courier, sansserif, sans serif" size="2"><a name="427076"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>struct</b></font><em>&nbsp;tag&nbsp;</em><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>arg;</b></font>
</font>
<br>
<font face="Courier New, Courier, sansserif, sans serif" size="2"><a name="427081"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>int&nbsp;ioctl&nbsp;(int&nbsp;</b></font><em>fd</em><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>,&nbsp;int</b></font><em>&nbsp;cmd</em><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>,&nbsp;struct&nbsp;</b></font><em>&nbsp;tag&nbsp;arg</em><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>);</b></font>
</font>
<p>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="427086"></a>The first argument <em>fd</em> is a file descriptor which is returned from opening the <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>/dev/vx/trace</b></font> device.  Each tracing device opened is a cloned device which can be used as a private kernel trace channel. The value of <em>cmd</em> is the ioctl command code, and <em>arg</em> is usually a pointer to a structure containing the arguments that need to be passed to the kernel. </font>
</p>

<p>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="427144"></a>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, <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>errno </b></font>is set to indicate the cause of the error. </font>
</p>

<p>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="427183"></a>The following ioctl commands are supported: </font>
</p>

<p>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="427187"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_ERROR_TRACE_INIT</b></font></font>
</p>
<p>
<a name="427814"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2">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 <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_DISCARD</b></font> 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 <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>read(2)</b></font> 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 <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>read</b></font>() returns an integral number of trace event records, not to exceed the number of bytes requested in the <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>read()</b></font> call; the return value from <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>read()</b></font> 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, <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>EAGAIN</b></font> 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 <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>read()</b></font>. If more trace records are available, subsequent reads will return those records. </font>
</p>
<p>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="427407"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_IO_TRACE_INIT</b></font></font>
</p>
<p>
<a name="427861"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2">The <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_IO_TRACE_INIT</b></font> ioctl initializes a kernel trace channel to return I/O trace data.  This command accepts <em>bufsize</em> as the argument.  Initially, no objects are selected for I/O tracing. To select objects to trace, issue the <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_IO_TRACE</b></font> ioctl. The <em>bufsize</em> 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 <em>bufsize </em>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 <em>bufsize </em>value of <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>(size_t)-1</b></font> will yield the maximum buffer size. </font>
</p>
<p>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="427510"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_IO_TRACE,VOLIOT_IO_UNTRACE</b></font> </font>
</p>
<p>
<a name="427912"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2">The <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_IO_TRACE</b></font> and <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_IO_UNTRACE</b></font> ioctls enable and disable, respectively, I/O tracing for particular sets of objects on an I/O tracing channel.  They both accept a <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>voliot_want_list</b></font> structure <em>tracelist</em> as the argument.  The <em>tracelist</em> argument specifies object sets.  The <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>voliot_want_list</b></font> structure specifies an array of desired object sets. Each object set is identified by a union of structures (the <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>voliot_want_set</b></font> union), each representing different types of object sets.  See the declaration of these structures in <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>voltrace.h</b></font> for more detail. </font>
</p>

<h3><font face="Arial, Helvetica, Geneva, sansserif, sans serif, Verdana" size="2" color="#000000">
<a name="427603"></a> FILES</font>
</h3>
<p>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="427609"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>/dev/vx/trace</b></font></font>
</p>
<p>
<a name="427929"></a><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2">The <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_IO_TRACE</b></font> and <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>VOLIOT_IO_UNTRACE</b></font> ioctls enable and disable, respectively, I/O tracing for particular sets of objects on an I/O tracing channel.  They both accept a <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>voliot_want_list</b></font> structure <em>tracelist</em> as the argument.  The <em>tracelist</em> argument specifies object sets.  The <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>voliot_want_list</b></font> structure specifies an array of desired object sets. Each object set is identified by a union of structures (the <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>voliot_want_set</b></font> union), each representing different types of object sets.  See the declaration of these structures in <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>voltrace.h</b></font> for more detail. </font>
</p>

<h3><font face="Arial, Helvetica, Geneva, sansserif, sans serif, Verdana" size="2" color="#000000">
<a name="427612"></a> SEE ALSO</font>
</h3>
<blockquote>
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><a name="427617"></a><a href="vxintro_vxvm_manpages47_452164.html#439378"><font color="#0000ff"><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>vxintro </b></font></font></a>(1M), <a href="vxtrace_vxvm_manpages78_430557.html#428493"><font color="#0000ff"><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>vxtrace </b></font></font></a>(1M), <a href="vxvol_vxvm_manpages85_441003.html#433596"><font color="#0000ff"><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>vxvol </b></font></font></a>(1M) <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>ioctl</b></font>(2), <font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>read</b></font>(2), <a href="vxconfig_vxvm_manpages94_426402.html#426260"><font color="#0000ff"><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>vxconfig </b></font></font></a>(7), <a href="vxiod_vxvm_manpages48_427282.html#426722"><font color="#0000ff"><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="2"><b>vxiod </b></font></font></a>(7) </font>
</blockquote>

<!-- End Main Topic Content -->

   </td>
  </tr>
 </table>
</div>

<div>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
 <tr>
  <td height="18" border="0" cellspacing="0" cellpadding="0" colspan="2" bgcolor="#FFFFFF">
  </td>
 </tr>
  <td align="left"><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="-2">&nbsp;&#94;&nbsp;<a href="vxtrace_vxvm_manpages99_427612.html" title="vxtrace">Return to Top</a></font>

  </td>
  <td align="right"><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="-2">&lt;&nbsp;<a href="vxiod_vxvm_manpages98_427949.html" title="Previous - vxiod">Previous</a>&nbsp;&nbsp;</font>
  </td>
 <tr>
   <td height="9" border="0" cellspacing="0" cellpadding="0" colspan="2" bgcolor="#FFFFFF">
   </td>
 </tr>

<!-- Footer Breadcrumbs -->
<tr>
<td bgcolor="#FFFFFF" colspan="2" height="15" align="right">
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="1">Product:  
<a href="vxvm_manpages_splashpage_docCD_vxvm_manpages1_103036.vxhd" title="Volume Manager Manual Pages for Storage Foundation title page ">Volume Manager Manual Pages for Storage Foundation</a>&nbsp;&nbsp;</font></td>
</tr>

<tr>
<td bgcolor="#FFFFFF" colspan="2" height="15" align="right">
<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="1">Manual:  
<a href="man7_titlepage_docCD_vxvm_manpages92_73700.vxhd" title="Miscellaneous (7) title page ">Miscellaneous (7)</a>&nbsp;&nbsp;</font></td>
</tr>


 <tr>
  <td colspan="2" align="left"><font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" color="#000000" align="right" size="-2">
<em>VERITAS Software Corporation
</em></font><br>

<font face="Verdana, Arial, Helvetica, Geneva, sansserif, sans serif" size="-2">www.veritas.com</font><br>
  </td>
 </tr>
</table>
</div>

</BODY>
  <!--
    *************************************************************************************
    * Copyright (c) 2005 VERITAS Software Corporation. All rights reserved. *

    VERITAS, VERITAS SOFTWARE, the VERITAS Logo, and VERITAS Software Documentation 
    are trademarks or registered trademarks of VERITAS Software Corporation 
    or its affiliates in the U.S. and other countries. Other names may be 
    trademarks of their respective owners. 

    Apache Jakarta Lucene:
    Apache Software License
    Version 1.1

    Copyright (c) 2000 The Apache Software Foundation. All rights reserved.

    Redistribution and use in source and binary forms, with or without modification, 
    are permitted provided that the following conditions are met:

    1. Redistributions of source code must retain the above copyright notice, this 
    list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright notice, this 
    list of conditions and the following disclaimer in the documentation and/or other 
    materials provided with the distribution.

    3. The end-user documentation included with the redistribution, if any, must include 
    the following acknowledgment: "This product includes software developed by the Apache 
    Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may 
    appear in the software itself, if and wherever such third-party acknowledgments 
    normally appear.

    4. The names "Apache" and "Apache Software Foundation" must not be used to endorse or 
    promote products derived from this software without prior written permission. For 
    written permission, please contact apache@apache.org.

    5. Products derived from this software may not be called "Apache", nor may "Apache" 
    appear in their name, without prior written permission of the Apache Software Foundation.

    THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, 
    BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
    PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION 
    OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 
    OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 
    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
    ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    This software consists of voluntary contributions made by many individuals on behalf 
    of the Apache Software Foundation. For more information on the Apache Software Foundation, 
    please see <http://www.apache.org/>. Portions of this software are based upon public domain 
    software originally written at the National Center for Supercomputing Applications, University 
    of Illinois, Urbana-Champaign.
    
    This product includes WebWindow Software developed by Horst Heistermann.
    *************************************************************************************
  -->
</HTML>
