userman.html

这是一个C程序分析工具

the output directory. </P>

<DL>
<DD><TT>r2inst /usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/rpngetch.c </TT></DD>

<DD><TT>r2inst /usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/rpngetop.c </TT></DD>

<DD><TT>r2inst /usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/rpnmain.c </TT></DD>

<DD><TT>r2inst /usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/rpnstack.c </TT></DD>
</DL>

<P><A NAME="compile"></A><B>3.5
Compiling the Instrumented Version</B> </P>

<P><B>Introduction<BR>
</B>After RECON instruments your source code, you will need to compile
the instrumented code. This may involve linking with libraries and non-instrumented
components. </P>

<P><B>Input<BR>
</B>The instrumented source code files will be used as input along with
other source files as needed for your particular system. </P>

<P><B>Processing<BR>
</B>The command you must give to compile will vary depending on the compiler
you use. Each compiler has a slightly different command line format. Some
compilers are part of a programming environment, and it may be easier to
use that environment to create a project file, and then let the environment
do the compile. </P>

<P>However your compiler works, here are some things to be careful of:
</P>

<UL>
<LI><A HREF="#r2protos"><CODE>r2protos.c</CODE></A> must be compiled and linked with
the instrumented source code. <CODE>r2protos.c</CODE> contains <A HREF="#instrumentation">instrumentation</A>
routines required by the instrumented source code. </LI><P>

<LI><CODE>r2.h</CODE>, <CODE>r2protos.h</CODE>, and <CODE>r2protos.c</CODE> must be present in the instrumented
source code directory. For the RPN example, you would copy these files
to <TT>/usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst</TT>. If instrumented files exist in multiple
directories, <CODE>r2protos.h</CODE> needs to be included in each of the directories.
</LI><P>

<LI>Be sure your compile command line includes one of the following macro 
definitions:  "-DSYS_UNIX" (Unix platforms) or "-DSYS_DOS" (MS-DOS
 platforms).  Alternatively, you can define either macro by uncommenting
 the appropriate line in the <CODE>r2.h</CODE> file.</LI><P>

<LI>Choose either the <A HREF="#normtrace">Normal Trace</A> or the <A HREF="#mintrace">Minimum
Trace</A> option. The Normal Trace option is the default. The Minimum Trace
option is selected by defining the preprocessor macro MIN_TRACE when compiling
R2PROTOS.C. This macro can be defined either on the compile command line
or else by adding a line to <CODE>r2.h</CODE>. </LI><P>
</UL>

<P>The following is an example of a compile command for the RPN example
using the UNIX Gnu C/C++ compiler:

<DL>
<DD><TT>gcc -o rpn -DSYS_UNIX rpnmain.c rpngetch.c rpngetop.c rpnstack.c
r2protos.c</TT> </DD>
</DL>

<P><B>Output<BR>
</B>Compilation produces an instrumented executable version of the target
program. For the RPN tutorial, an instrumented executable file called <TT>rpn</TT>
is produced. </P>

<P><A NAME="test"></A><B>3.6
Testing the Instrumented Version</B><BR>
</P>

<P><B>Introduction<BR>
</B>To locate a feature using the instrumented executable, run test cases
that exhibit the feature and others that do not. Usually only a few cases
are needed. For the RPN Calculator to locate the multiplication feature,
we suggest one case for each of the four features: multiply, add, subtract,
and divide. (See Table 1). The instrumented executable will create a trace
file from each case. </P>

<P><B>Input<BR>
</B>RECON needs to know what name to give each trace file. To specify the
trace file name, and an optional comment about the test, run <CODE>r2test</CODE> before
each test run. <CODE>r2test</CODE> stores the trace file name and the comment in a temporary
file named <CODE>r2tmp.dat</CODE> where the instrumented executable can find them. After
the test is finished, run <CODE>r2end</CODE> to delete this temporary file. Ensure <CODE>r2test</CODE> 
and <CODE>r2end</CODE> are in the execution path.  (If the
instrumented executable does not find the <CODE>r2tmp.dat</CODE> file, it will name
the trace <CODE>unknown.r2t</CODE>. You can rename it after the test.) </P>

<P><B>Processing<BR>
</B>Here is how to run the multiply test case in the RPN example:</P>

<DL >
<DD><CODE>r2test -t out/multiply.r2t -c &quot;Testing multiplication, input is
6 3 *&quot;</CODE><BR> </DD>
</DL>

<DD>RPN<BR> </DD>

<DD>&gt;Welcome to the Reverse Polish Calculator </DD>

<DD>&gt;Enter Two Numbers Separated by White Space </DD>

<DD>&gt;then an operator. (i.e., 2 3+) </DD>

<DD>&gt;Enter Q anytime to Quit </DD>

<DD>6 3 *<BR> </DD>

<DD>&gt;18 </DD>

<DD>Q<BR> </DD>
<P>

<DD><CODE>r2end</CODE><BR> </DD>

<P>Repeat the process for add, subtract and divide by running <CODE>R2TEST</CODE> with<BR>
<CODE>-t out/add.r2t,<br> 
-t out/subtract.r2t<br></CODE> 
and <CODE>-t out/divide.r2t</CODE><br> 
respectively
and executing RPN replacing the * with +, -, and /. </P>

<P><B>Output<BR>
</B>Output trace files named <CODE>multiply.r2t, add.r2t, subtract.r2t</CODE>, and <CODE>divide.r2t</CODE>
are created that record each branch that was encountered, the line number,
the switch value (for switch statements only), the string length of the
source file name, and the source file name. An example of the trace file
is shown below: </P>

<CODE>
<PRE>        #Testing multiplication, input is 6 3 *
        F 14 31 /usr/cs/&lt;usrname&gt;/inst/rpngetop.c
        F 17 31 /usr/cs/&lt;usrname&gt;/inst/rpngetop.c
        T 20 31 /usr/cs/&lt;usrname&gt;/inst/rpngetop.c
        F 21 31 /usr/cs/&lt;usrname&gt;/inst/rpngetop.c
        F 23 31 /usr/cs/&lt;usrname&gt;/inst/rpngetop.c
        T 28 31 /usr/cs/&lt;usrname&gt;/inst/rpngetop.c
        F 15 31 /usr/cs/&lt;usrname&gt;/inst/rpngetch.c
        T 23 30 /usr/cs/&lt;usrname&gt;/inst/rpnmain.c
        S 25 48 30 /usr/cs/&lt;usrname&gt;/inst/rpnmain.c
        T 11 31 /usr/cs/&lt;usrname&gt;/inst/rpnstack.c
        E 12 14 /usr/cs/&lt;usrname&gt;/inst/rpngetch.c
        E 14 14 /usr/cs/&lt;usrname&gt;/inst/rpngetop.c
        T 14 31 /usr/cs/&lt;usrname&gt;/inst/rpngetop.c
        F 14 31 /usr/cs/&lt;usrname&gt;/inst/rpngetop.c
        etc....</PRE>
</CODE>
<P>
<HR><A NAME="analyze"></A><B>3.7
Analyzing the Test Results</B> </P>

<P><B>Introduction<BR>
</B>For the analysis, you must create a list file that specifies which
of your test cases exhibited the feature you are looking for. RECON then
determines which branch statements seem to be most closely related to that
feature. </P>

<P><B>Input<BR>
</B>The inputs are: </P>

<UL>
<LI>List file - Listing of the trace files indicating which ones exhibit
the feature. The list file also specifies the kind of analysis to perform.
(See Section 7 for the full list file format) </LI>

<LI>Source code files - Original source code files of the target program.
</LI>

<LI>Test case trace files - One trace file from each test. </LI>
</UL>

<P>For the RPN tutorial, to locate the multiply feature, create a list
file called MULTIPLY.LST with the following contents.  Case is 
important for the &quot;D&quot;, &quot;Y&quot;,  and &quot;N&quot;. </P>

<DD>D </DD>

<DD>&gt;&gt;&gt;&gt;&gt; </DD>

<DD>95 </DD>

<DD>/usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/out/add.r2t </DD>

<DD>N </DD>

<DD>/usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/out/divide.r2t </DD>

<DD>N </DD>

<DD>/usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/out/subtract.r2t </DD>

<DD>N </DD>

<DD>/usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/out/multiply.r2t </DD>

<DD>Y </DD>

<P><B>Processing</B> <BR>
To run the analysis program <A HREF="#r2analyz"><CODE>r2analyz</CODE></A>, type the
command: </P>

<DL>
<DD><CODE>r2analyz -r /usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/out/multiply.lst -p /usr/cs/&lt;usrname&gt;/&lt;RPN source file dir&gt;/inst/out/</CODE></DD>
</DL>

<P>Where -r specifies the list file to use and the -p specified the location
to place the output. For options, refer to the description of <CODE>r2analyz</CODE>
in Section 7. </P>

<P><B>Output<BR>
</B>The default output of the analysis program is an annotated listing
file of the user's source code for each source code file that was instrumented
and met the conditions of the analysis. The annotated files have the same
names as the original source files except the extension has been changed
to <TT>.out</TT>. Each control statement that met the conditions of the
analysis is annotated with <STRONG><TT>&gt;&gt;&gt;&gt;&gt;</TT></STRONG> and the values
that are associated with the control statement. (See <B><A HREF="overview.html">RECON
- OVERVIEW</A></B> for an example of the annotated listing output file.)
</P>

<P>
<HR><A NAME="using"></A><B>4.
USING RECON OPTIONAL INSTRUMENTATION FEATURES</B> </P>

<P>We have found that RECON users often want greater control over the tracing
process. The following additional calls to functions in <CODE>r2protos.c</CODE> can
be inserted by hand at key points in the users program to control tracing:
</P>

<OL>
<LI><B>Suspend Tracing:<BR>
</B>The following functions may be used to suspend tracing, for example,
around a particularly tight loop: </LI>

<PRE>int R2Suspend();
int R2Resume();
</PRE>

<P>R2Suspend suspends writing to the trace file until R2Resume, the resume
command, is given. Both return a 0 if no errors occur. </P>

<LI><B>Insert Comment:<BR>
</B>The following function may be used to insert comment messages. </LI>

<PRE>int R2Comment(char * msg_ptr);
</PRE>

<P>R2Comment writes a comment message to the trace file. It returns a 0
if no errors occur. </P>

<LI><B>Change to a New Trace File:<BR>
</B>The following function may be used to switch to a new trace file: </LI>

<PRE><CODE>int R2NewTrace(char *r2newfile)</CODE>;
</PRE>

<P>R2NewTrace closes the current trace, if it is open, and opens the new
trace file <CODE>r2newfile</CODE>. The trace file path name can be any string acceptable
to the fopen function. It returns a 0 if no errors occur. </P>
</OL>

<P>
<HR><A NAME="unix"></A><B>5.
UNIX MULTI-PROCESS PROGRAMS</B> </P>

<P>Multi-process programs are difficult to trace since the different processes
may attempt to write to the same trace file and may produce corrupted output.
We have provided an option that may work for multi-process systems under
UNIX, but since there are many dialects of UNIX and many compilers, we
only offer it on a &quot;try it and see&quot; basis. In this option, the
code in R2PROTOS.C will try to write to a UNIX message queue which is,
in turn, written to the trace file. UNIX handles contention among the different
processes. </P>

<P>  When this option is used, R2Testq and R2Endq are substituted for R2Test and R2End.  
If you have not compiled these two programs, then do so using, for example, gcc:
<DL>
<DD><CODE>gcc -o r2testq -DSYS_UNIX r2testq.c</CODE></DD>
<DD><CODE>gcc -o r2endq -DSYS_UNIX r2endq.c</CODE></DD>
</DL>
You also need to ensure the resulting files are in the executable path.

<P>To use this option, when you compile <CODE>r2protos.c</CODE> (and your program), 
define a macro named <CODE>MESSAGE_Q</CODE>. A typical command line to compile your
multi-process program named &quot;user&quot; from a file named &quot;user.c&quot;
might be: </P>

<P><TT>gcc -o user -DMESSAGE_Q -DSYS_UNIX user.c r2protos.c</TT> </P>

<P>Before running each test, run the program < CODE>r2testq</CODE> as a background process
instead of using <CODE>r2test</CODE> as described earlier. <CODE>r2testq</CODE> creates the message
queue, &quot;listens&quot; for trace records coming from the queue and
writes them to the trace file. Wait about 5 seconds to give UNIX time to
create the message queue before starting the test. After the test is complete,
run <CODE>r2endq</CODE> instead of <CODE>r2end</CODE>. <CODE>r2endq</CODE> tells <CODE>r2testq</CODE> to shut down the queue
and close the trace file. Again, it is best to wait a few seconds before
doing another test to be sure the queue has shut down. </P>

<P>The complete sequence for one test could thus be similar to the following
example: </P>

<BLOCKQUOTE>
<TT>r2testq -t &quot;trace&quot; -c &quot;test of functionality A&quot;
&amp;<BR>
{wait 5 seconds}<BR>
user {any input or output for your program named &quot;user&quot;}<BR>
r2endq<BR>
{wait 5 seconds}</TT><BR>
</BLOCKQUOTE>
<P>Note the &quot;<STRONG>&amp;</STRONG>&quot; on the <CODE>r2testq</CODE> command to be sure that <CODE>r2testq</CODE> is
a background process. 
<HR><A NAME="enhance"></A><B>6.
RECON ENHANCEMENTS</B> </P>

<P>March 1997 - RECON is being modified to provide software reconnaissance
on ADA programs. This work is being completed by the Pensacola Software
Engineering project team. </P>

<P>
<HR><A NAME="recon"></A><B>7.
RECON COMMANDS AND FILES</B> </P>

<P><B>7.1 RECON Commands</B> </P>

<P><A NAME="r2analyz"></A><B>R2ANALYZ</B>
- This is the RECON program that analyzes your trace files to locate where
a feature is located. The default is to output the annotated source listing,
print limited progress information, and display error messages to your
screen. The options are not case sensitive.  There must be a space 
between the option switch (-v or -p) and the option argument (i.e. &lt;list file&gt;)</P>

<PRE><CODE>
    r2analyz -r &lt;list file&gt; -p &lt;output directory&gt; [ ? | -h |-q | -v ] [-s]
</CODE></PRE>
where

<PRE>
        -r = List filename location
        -p = output directory to place analysis
     ?, -h = Brief listing of the options like this list
        -q = No terminal output, not even errors