.\" Motif
.\"
.\" Copyright (c) 1987-2012, The Open Group. All rights reserved.
.\"
.\" These libraries and programs are free software; you can
.\" redistribute them and/or modify them under the terms of the GNU
.\" Lesser General Public License as published by the Free Software
.\" Foundation; either version 2 of the License, or (at your option)
.\" any later version.
.\"
.\" These libraries and programs are distributed in the hope that
.\" they will be useful, but WITHOUT ANY WARRANTY; without even the
.\" implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
.\" PURPOSE. See the GNU Lesser General Public License for more
.\" details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with these librararies and programs; if not, write
.\" to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
.\" Floor, Boston, MA 02110-1301 USA
...\" 
...\" 
...\" HISTORY
# $XConsortium: ch05.sm /main/3 1995/07/13 20:09:29 drk $
...\"  (c) Copyright 1992 OPEN SOFTWARE FOUNDATION, INC.
.H 1 "Library Reference"
.P
Two libraries shipped with QATS, \*LlibCommon.a\*O and \*LlibMalloc.a\*O
contain functionality which is useful both within and outside of 
automated tests. The new features of these libraries are discussed in
this chapter.
.H 2 "The Malloc Library"
.P
This release includes a memory-management testing library, based on the
Conor Cahill malloc package, with modifications made by OSF. The
library is compiled into \*LlibMalloc.a\*O.
This malloc package checks for the following types of usage errors:
.BL
.LI
Accessing memory which has already been freed.
.LI
Accessing uninitialized memory.
.LI
Failures which occur within string functions such as \*Lstrcpy\*O.
.LE
.P
It also provides a block-tracking system to help locate memory leaks.
Keep in mind when debugging tests that there is a fixed amount of memory 
allocated during class initialization which is never freed, even if all
the widgets of that class are destroyed. This may look like a memory leak
but is not. In addition, fragmentation can cause apparent memory leaks
where none exist.
.H 3 "Building With \*LlibMalloc\*O"
.P
Any test which calls \*LCommonTestInit\*O can be compiled 
with the malloc package in two steps. First, simply remake the
Makefile in that test directory with the command:
.sS
.iS
make IMAKE_DEFINES="-DDebugLib" Makefile
.iE
.sE
.P
One can set up a directory for both Automated and Malloc testing by
rebuilding the Makefile with this command:
.sS
.iS
make IMAKE_DEFINES="-DAUTOMATION -DDebugLib" Makefile
.iE
.sE
.P
After this step, rebuild the test(s). All calls to \*LXtMalloc\*O, \*LXtRealloc\*O and \*LXtFree\*O will be traced.
.P
To use this malloc library outside of QATS, your application must
perform two steps.  The first is to make a call to \*LMallocInit()\*O
in the beginning of the program being tested and make a call
to \*LMallocExit()\*O at the end of the program.  The second is
to link with the malloc library.  Note: \*LMallocInit\*O requires
two parameters: the application shell widget ID and the
display ID.  (See the source file \*LMallocInit.c\*O). 
.P
Note that a side effect of using \*LMallocInit()\*O is that several
signals will be handled by the malloc library, thereby eliminating
any signal previously defined by your program.  The signals which
get defined are: \*LSIGTERM\*O, \*LSIGSEGV\*O, \*LSIGINT\*O,
\*LSIGHUP\*O, and \*LSIGQUIT\*O.
Upon the occurrence of any of these signals, \*LMallocDump()\*O
will be called and the program will terminate.	
.H 3 "Default Behavior"
.P
A fill pattern is written into any memory allocated by
\*LXtMalloc\*O, \*LXtCalloc\*O, \*LXtRealloc\*O.  The fill pattern by default
is \*L0x01\*O.  Using this pattern makes it more likely that any use
of uninitialized memory will produce an error.
.P
When \*LXtFree\*O is called, several validity checks are made on 
the pointer being passed.  The data in the malloc block beyond 
the size requested in the initial malloc is checked to verify 
that it is still filled with the original fill pattern.
This is useful for catching things like:
.sS
.iS
ptr = XtMalloc(5);
ptr[5] = '\0';  
.iE
.sE
.P
The freed block is filled with a different fill pattern so that
you can easily determine if you are still using freed space.
The default fill pattern for the freed areas is \*L0x02\*O.  For 
example:
.sS
.iS
ptr = XtMalloc(20);
bptr = ptr+10;
.sp
/* Do something useful with bptr */
...
.sp
XtFree(ptr);
.sp
/*
 *  Now try to do something useful with bptr.  It
 *  should be trashed enough so that would cause
 *  real problems and when debugging, you would see
 *  that it would be filled with 0x02's.
 */
.sp
.iE
.sE
.P
Whenever a \*Lbstring(3)\*O, \*Lstring(3)\*O, or \*Lmemory(3)\*O 
function is called
and the environment variable \*LMALLOC_CHECK_STRING\*O is set to true,
the validity of the operation is checked \*Eif and only if\*O the data being
referenced is in the malloc arena.   For example, 
.sS
.iS
ptr = XtMalloc(5);
strcpy(ptr,"123456");  
/* oops, too much!  wrote two extra chars, '6' and '\0' */
.iE
.sE
.P
Note that all output (including errors and warnings) from the 
malloc library goes to standard output (\*Lstdout\*O) by default.  
Standard output can be 
redirected to an output file by setting the environment variable
\*LMALLOC_OUT_FILE\*O to a file name.
.P
A routine exists in the malloc library, \*LMallocDump()\*O,
which will dump the malloc chain and status of any outstanding
memory at the time it is called.  
.P
For tests in the QATS, a \*LMallocDump()\*O will occur
automatically at the end of the test program.  The "end" of
a test program is defined as any of the following:
.BL
.LI
When the following signals occur: \*LSIGTERM\*O, \*LSIGSEGV\*O, 
\*LSIGINT\*O, \*LSIGHUP\*O, \*LSIGQUIT\*O
.LI
When the \*LExit\*O button in the control dialog box is selected
.LI
When \*LClose\*O is selected from the window menu
.LE
.H 3 "Controlling libMalloc Behavior"
.P
You may modify the functionality of the malloc package by
using the following environment variables:
.VL 2.25i
.LI "\*LMALLOC_ALLOC_CHAR\*O"
The fill character written into allocated
memory.  Default: \*L0x01\*O.  
.LI "\*LMALLOC_FREE_CHAR\*O"
The fill character written into freed
memory.  Default: \*L0x02\*O.  
.LI "\*LMALLOC_OUT_FILE\*O"
The name of the file to which all malloc output is written.
Default: \*Lstdout\*O.
.LI "\*LMALLOC_END_DUMP\*O"
When true, tells the library to dump out the malloc chain and leak
information at the end of a program.
Default: \*Ltrue\*O.
.LI "\*LMALLOC_LOG_INFO\*O"
When true, all calls to \*LXtMalloc\*O, \*LXtRealloc\*L, 
\*LXtCalloc\*O, and \*LXtFree\*O, are logged when they occur.
Default: \*Lfalse\*O.
.LI "\*LMALLOC_CHECK_STRING\*O"
When true, check for problems when string/memory functions are referenced.
Default: \*Lfalse\*O. Note: this feature has a significant performance
impact.
.LE
.H 2 "Test Convenience Routine Library (\*LlibCommon.a\*O)"
.P
The library \*LlibCommon.a\*O groups a number of functions which
can be called from tests. Several of these, like \*LCommonTestInit\*O
and \*LCommonPause\*O have been described elsewhere. In addition
to test convenience functions, \*LlibCommon.a\*O provides additional
functionality that can be useful for manual as well as automated
testing. These functions and features are described in the following
sections.
.H 3 "Test Results Bookkeeping for Manual testing"
.P
A feature has been added to the \*Ltests/lib/Manual/Common\*O library
which can be useful to keep track of successes and failures during manual
(non-automated) testing. When this library is compiled with the flag
\*L-DREGRESSION\*O, the single \*LContinue\*O button in the Instruction
Box is replaced with two buttons, \*LPass\*O and \*LFail\*O. The
number of passes and fails in each test are tallied and printed out 
to a file called \*LRUN_output\*O. This file will be appended by each
test run in the same directory.
.H 3 "Command Line Options"
.P
A large number of command lines are supported by convenience routines
which parse the command line. A summary of the command line options
follows.
.VL 1i
.LI "\*L-l\*O"
Disable displaying of the MessageBox for user 
instructions (Ignore Pause())
.LI "\*L-I\*V file\*O"
Read an alternative instruction file. The default is
<test_name>.dat.
.LI "\*L-h\*O"
Print the usage message.
.LI "\*L-w \*Vnumber\*O"
Specify width of MessageBox for user instructions. 
Default is 80.
.LI "\*L-u \*Vstring\*O"
Specify a string which will available to the 
test writer as the global variable \*Lchar * UserData\*O.
.LI "\*L-f \*Vfont\*O"
Use \*Vfont\*O as the "fallback" font to be used when 
a font specified in the test code is not available. The default is \*Lfixed\*O.
.LI "\*L-p \*Vfont\*O"
Specify the font to be used in the MessageBox for user
instructions. Default is \*Lfixed\*O.
.LE
.P 
The following options are for use only for the \*LlibCommon\*O library
in \*Ltests/Auto/lib/Common\*O.
.VL 1i
.LI "\*L-a\*O"
Generate full error reporting on visuals in output file.
.LI "\*L-r\*O"
Record mode.
.LI "\*L-b\*O"
Batch mode for playback (default).
.LI "\*L-m\*O"
Interactive comparison of visuals.
.LI "\*L-c\*O"
Visual comparisons ignored.
.LI "\*L-C \*Vcolor\*O"
Display differences using \*Vcolor\*O in the interactive window. For use only with the \*L-m\*O flag.
.LI "\*L-D \*Vseconds\*O"
Execute a delay of \*Vseconds\*O. 
.LI "\*L-W\*O"
Produce xwd-format window dumps files for visual failures.
.LI "\*L-S \*Vfile\*O"
Alternative name for script file.
.LI "\*L-O \*Vfile\*O"
Alternative name for output file.
.LI "\*L-V \*Vfile\*O"
Alternative name for visual image file.
.LI "\*L-T\*O"
Trace mode; print each script command as executed.
.LE
.H 3 "New Callable Functions"
.sS
.iS
void CommonGetOptions( int \*Vargc\*L, char **\*Vargv\*L )
.iE
.sE
.VL 1.5i
.LI "Input:"
\*Vargc\*O, \*Vargv\*O
.LI "Output:"
None
.LI "Purpose:"
This function will read the command line options and 
set the appropriate flags to represent those options.
Called from \*LCommonTestInit()\*O.
.LE
.sS
.iS
void CommonTestInit( int \*Vargc\*L, char **\*Vargv\*L )
.VL 1.5i
.LI "Input:"
\*Vargc\*O, \*Vargv\*O
.LI "Output:"
None
.LI "Purpose:"
Performs the following functions:
.VL .5i
.LI "1)"
Set up signal handlers (see section
4.1.2 for specific signals).
The signal handler simply prints a message 
and exits.
.LI "2)"
Call \*LGetOptions()\*O to parse the command
line options.
.LI "3)"
Call \*LXtToolkitInitialize()\*O to
initialize the Intrinsics.
.LI "4)"
Create an Application context.
.LI "5)"
Create a connection to the display by calling
\*LXtOpenDisplay()\*O. A global variable \*Ldisplay\*O
is set to the return value.
.LI "6)"
Create an ApplicationShell with
XmNallowShellResize set to true. The global
variable \*LShell1\*O is set to the return value.
.LE
.LI "Globals:"
Global variables \*Ldisplay\*O and \*LShell1\*O are initialized.
.LE
.sS
.iS
XtCallbackProc CommonGenericCB( Widget \*Vw\*L, XtPointer \*Vclient_data\*L, XtPointer *\*Vcall_data\*L)
.iE
.sE
.VL 1.5i
.LI "Input:"
Normal callback parameters
.LI "Output:"
None
.LI "Purpose:"
This is a "generic" callback routine that will simply
print to \*Lstdout\*O the reason why the callback was triggered.
It can be used when a simple verification of a callback
is needed.
.LE
.sS
.iS
Pixel CommonGetColor( char *\*VColorString\*L )
.iE
.sE
.VL 1.5i
.LI "Input:"
A character string corresponding to a valid color in
the rgb.txt file on a system. 
.LI "Output:"
A color cell entry corresponding to the passed color
string. If the color does not exist, NULL will be
returned.
.LI "Purpose:"
This routine will convert a string representation of
a color into a Pixel value.
.LE
.sS
.iS
XmFontList CommonGetFontList( char *\*VFontString\*L )
.iE
.sE
.VL 1.5i
.LI "Input:"
A character string describing a font. 
.LI "Output:"
The corresponding XmFontList.
.LI "Purpose:"
This routine will convert a string representation of
a font into a XmFontList. If the specified font 
does 
not exist on that system, then \*Ldefault_font\*O is used.
The variable \*Ldefault_font\*O can be set on the command line.
A default value for \*Ldefault_font\*O is defined in 
the file \*Ltestlib.h\*O.
.LE
.sS
.iS
char CommonCsToRs( XmString \*Vcs\*L )
.iE
.sE
.VL 1.5i
.LI "Input:"
An XmString.
.LI "Output:"
A character string representation of that XmString.
.LI "Purpose:"
This function will convert a simple one-segment compound
string into a regular character string.
.LE
.sS
.iS
void CommonPause()
.iE
.sE
.VL 1.5i
.LI "Input:"
None
.LI "Output:"
None
.LI "Purpose:"
This function will place on the screen at (500, 0)
an InformationDialog which contains instructions
to the user, read from a \*L.dat\*O file.
.LE
.sS
.iS
void CommonDumpHierarchy(Widget \*Vwidget\*L, FILE *\*Vfileptr\*L)
.iE
.sE
.VL 1.5i
.LI "Input:"
A widget and a pointer to the output file.
.LI "Output:"
None
.LI "Purpose:"
This function will "dump" all the widget names 
(fetched with \*LXtName\*O)
which are descendents of the input widget. 
The output will be written
to the file \*Vfileptr\*O.
.LE
.P
Note: you may dump the hiearchy of any test at any time by pressing
\*L<Ctrl> Btn1\*O on the \*LExit\*O button of the test's InstructionBox.
.\".S +2