<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-8105D1FC-DFFE-59F0-A664-3DA44F002F47" xml:lang="en"><title>Enabling File Server Tracing</title><shortdesc>This document describes how to enable trace points in the
file server client API (EFSRV.DLL), the file system API (*.FSY) ,
and/or the proxy drive API. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-E4208794-E751-4626-A457-FB81B330AC9E"><title>Introduction</title> <p>Enabling a trace point results in trace data being output to
the trace buffer. </p> <p>Tracing can be enabled or disabled (i.e.
compiled in or out) at build time. By default file server tracing
is enabled in debug builds of EFSRV.DLL and EFILE.EXE and disabled
in release builds. To enable tracing in release builds, there are
two options: </p> <ul>
<li id="GUID-CE4CBA1C-D699-568D-B97D-98CD01E7ADAC"><p>replace the
release builds of <filepath>EFSRV.DLL</filepath> /<filepath>EFILE.EXE</filepath> with their debug equivalents. </p> </li>
<li id="GUID-76F59D55-BE9A-54E2-9A77-068F292334B0"><p>rebuild <filepath>EFSRV.DLL</filepath> /<filepath>EFILE.EXE</filepath> using <filepath>efsrv_instrumented.mmp</filepath> /<filepath>efile_instrumented.mmp</filepath>. </p> </li>
</ul> <p>Tracing can also be enabled or disabled at run time or at
device startup. For more information, see <b>Symbian^3 Tools Guide
&gt; Debugging</b>. </p> <p>The level of tracing required may be configured
by selecting one or more of the primary filters and one or more of
the secondary filters from the list below: </p> <codeblock id="GUID-DDA48DE7-651D-54D4-A3EA-81C053D5F4BC" xml:space="preserve">//Primary filters
EPanic = 192            // to trace panics
EError = 193            // to trace errors
EBorder = 195,            // to trace API calls</codeblock> <codeblock id="GUID-3253FF5A-ABAC-5A2D-9CE9-D420B855FB88" xml:space="preserve">//Secondary filters
EF32TraceUidEfsrv         =     0x100039e4 //    (268450276 in decimal)
EF32TraceUidFileSys        =    0x10286575 //    (271082869 in decimal)
EF32TraceUidProxyDrive    =    0x10286576 //    (271082870 in decimal)</codeblock><p> For more information on capturing the trace data, see <b>Symbian^3
Tools Guide &gt; Debugging</b>.  </p> </section>
<section id="GUID-AF241F65-5BCA-4BDA-9852-EF6033574A5E"><title>APIs </title> <p>The following table lists the classes to which the trace points
have been added. It has been divided into three broad categories as
shown below. </p> <ul>
<li id="GUID-930F772C-DC22-5D44-92D5-1EED6CDC02A9"><p> <b>File system</b>  </p> <ul>
<li id="GUID-938ED57F-0365-56BA-BD78-854CAE8BC344"><p> <xref href="GUID-0012B043-9FC4-3953-928E-CB6107E0486A.dita"><apiname>CFileSystem</apiname></xref>  </p> </li>
<li id="GUID-5A54ADD0-2F79-54A2-8725-EE738F51FC5F"><p> <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita"><apiname>CMountCB</apiname></xref>  </p> </li>
<li id="GUID-87CD0966-EE3B-5517-B69D-024B308EB4B1"><p> <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita"><apiname>CFileCB</apiname></xref>  </p> </li>
<li id="GUID-08DCCC4C-2A4B-560C-96C2-55C949086F4B"><p> <xref href="GUID-B19ADEA9-5018-3773-92BC-C16306D15043.dita"><apiname>CDirCB</apiname></xref>  </p> </li>
<li id="GUID-901B069A-A234-5238-94C0-B88723DA0698"><p> <xref href="GUID-E0C22CEA-845F-37A2-85DE-0ACD7927FA41.dita"><apiname>CFormatCB</apiname></xref>  </p> </li>
</ul> </li>
<li id="GUID-54DAF9C2-385A-5C5D-B808-DD42BD96D2B2"><p> <b>Proxy drive</b>  </p> <ul>
<li id="GUID-D082BF1C-A7F1-597D-BE7E-19FDAFE25368"><p> <xref href="GUID-F47F56E4-3754-365B-B529-53C1D2A29503.dita"><apiname>CLocalProxyDrive</apiname></xref>  </p> </li>
<li id="GUID-7115117E-68B1-5CCB-BEAE-668CF45DE9AD"><p> <xref href="GUID-FAFF712B-2295-3907-B839-D77F052160DA.dita"><apiname>CBaseExtProxyDrive</apiname></xref>  </p> </li>
</ul> </li>
<li id="GUID-ABC75EC4-EBBE-5F85-AA09-A1E77B121FBC"><p> <b>File server</b>  </p> <ul>
<li id="GUID-54E6118B-454D-50B6-8BA1-6C5A74E6A70C"><p> <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref>  </p> </li>
<li id="GUID-E9839BE3-3F7B-54BE-A52A-ECEBC4CE7691"><p> <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref>  </p> </li>
<li id="GUID-5D365808-C2C1-5CC3-9E69-1423C47CBCE5"><p> <xref href="GUID-12AE154F-7741-38C0-ADFE-9784FCF5E516.dita"><apiname>RDir</apiname></xref>  </p> </li>
<li id="GUID-D4F74F2A-F919-5AB9-89EA-1C45420E4391"><p> <xref href="GUID-9D7E765B-6872-3EB9-9D5B-1503FA466EC1.dita"><apiname>RFormat</apiname></xref>  </p> </li>
<li id="GUID-39021B3E-2F79-51A7-8158-4D08B94CCF4D"><p> <xref href="GUID-118CCC9E-C58B-3AA0-86A8-219914E7E7BC.dita"><apiname>RPlugin</apiname></xref>  </p> </li>
<li id="GUID-264C14C5-69D3-5662-9BFD-15B7FCB22F00"><p> <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita"><apiname>CFileMan</apiname></xref>  </p> </li>
<li id="GUID-817F4158-5F9F-5D21-9FA1-42D5EC6F774F"><p> <xref href="GUID-C657AF2D-1183-3CD2-ACAF-3B0B00FC91BB.dita"><apiname>CDirScan</apiname></xref>  </p> </li>
</ul> </li>
</ul> <p>Trace points have been added to the public exported functions
of the classes listed above. As an example, the code fragment below
illustrates how the tracepoints have been added and what type of information
is output for the Open function of the <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> class: </p> <codeblock id="GUID-44DCCB86-9835-5A03-A17C-A78F43A58FD6" xml:space="preserve">
EFSRV_EXPORT_C TInt RFile::Open(RFs&amp; aFs,const TDesC&amp; aName,TUint aMode)
{
TRACEMULT3(UTF::EBorder, UTraceModuleEfsrv::EFileOpen, MODULEUID, aFs.Handle(), aMode, aName);

aMode &amp;= ~EFileBigFile;
TInt r = CreateSubSession(aFs,EFsFileOpen,TIpcArgs(&amp;aName,aMode));

TRACERET2(UTF::EBorder, UTraceModuleEfsrv::EFileOpenReturn, MODULEUID, r, SubSessionHandle());

return r;
}</codeblock> <p>A sample trace output is as shown: </p> <codeblock id="GUID-A7782683-9A99-5B9B-AD52-81CC236CB7D1" xml:space="preserve">RFile::Open() sess 0x00008000 mode 0x00000100 FileName Z:\SYS\DATA\ESTARTFILESYSTEMS.TXT</codeblock> </section>
<section id="GUID-A46311CE-B4C4-4BE9-A698-5DC1C18D6C60"><title>Interpretation
of the trace data</title> <p>Symbian does not currently provide a
tool for decoding file server trace data (though hopefully this will
change in the near future). The data can, however, be interpreted
by examining the following two publicly exported header files which
provides detail of what fields are output by each tracepoint. </p> <ul>
<li id="GUID-3032957A-5D64-57AD-98FD-DF82D6959C10"><p> <filepath>\epoc32\include\utraceefsrv.h </filepath>  </p> </li>
<li id="GUID-8C8C91AD-757A-5A79-861B-2686178FB154"><p> <filepath>\epoc32\include\utraceefile.h</filepath>  </p> </li>
</ul> <p>For example: </p> <codeblock id="GUID-2B0DD8BA-5AC5-5369-8410-4A21B987D926" xml:space="preserve">
/** @SYMTraceFormatString "RFile::Replace() sess %x mode %x FileName %*S" */
EFileReplace</codeblock> <p>In the above example the trace record
will contain the session <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref> handle, the file open
mode and the filename. </p> </section>
</conbody><related-links>
<link href="GUID-7B477BA5-CC5B-56A2-82BC-E1BC0049FECB.dita"><linktext>Kernel
Trace Tool Overview</linktext></link>
</related-links></concept>