Man Page discover.1




NAME

     discover -	Memory Error Discovery Tool


SYNOPSIS

     discover
	  [-?]	[-h] [-a] [-b browser] [-c [ -	|  lib	|  file]]
	  [-D dir]  [-e	 num]  [-E  num] [-f] [-F [parent|child]]
	  [-H html_file] [-i] [-k] [-K]	[-l] [-m]  [-n]	 [-N lib]
	  [-o file]  [-s]  [-S	num] [-T] [-v] [-V] [-w	txt_file]
	  target


DESCRIPTION

     Memory Error Discovery Tool (Discover) is	a  tool	 used  by
     software  developers to detect programming	errors related to
     the allocation and	use of program memory at runtime.

     Examples of errors	detected by Discover include:
	  * Accessing uninitialized memory.
	  * Reads from and writes to unallocated memory.
	  * Accessing memory beyond allocated array bounds.
	  * Use	of freed memory.
	  * Freeing wrong memory blocks.
	  * Memory leaks.

     Here is a simple example of  preparing,  instrumenting,  and
     running an	executable:

     % cc -g -O2 test.c	-o test.prep
     % discover	-w - -o	test.disc test.prep
     % ./test.disc
     ERROR (UMR): accessing uninitialized data from address 0x5000c (4 bytes) at:
	  foo()	+ 0xdc	<ui.c:6>
	       3:    int *t;
	       4:    foo() {
	       5:     t	= malloc(5*sizeof(int));
	       6:=>   printf("%d0, t[1]);
	       7:    }
	       8:
	       9:    main()
	  main() + 0x1c
	  _start() + 0x108
	 block at 0x50008 (20 bytes long) was allocated	at:
	  malloc() + 0x260
	  foo()	+ 0x24	<ui.c:5>
	       2:
	       3:    int *t;
	       4:    foo() {
	       5:=>   t	= malloc(5*sizeof(int));
	       6:     printf("%d0, t[1]);
	       7:    }
	       8:
	  main() + 0x1c
	  _start() + 0x108


     ***************** Discover	Memory Report *****************

     1 block at	1 location left	allocated on heap with a total size of 20 bytes

	 1 block with total size of 20 bytes
	  malloc() + 0x260
	  foo()	+ 0x24	<ui.c:5>
	       2:
	       3:    int *t;
	       4:    foo() {
	       5:=>   t	= malloc(5*sizeof(int));
	       6:     printf("%d0, t[1]);
	       7:    }
	       8:
	  main() + 0x1c
	  _start() + 0x108

     DISCOVER SUMMARY:
	  unique errors	  : 1 (1 total,	0 filtered)
	  unique warnings : 0 (0 total,	0 filtered)


     To	use Discover, the input	binary	must  be  compiled  using
     compiler version Sun Studio 12 Update 1, Oracle Solaris Stu-
     dio 12.2, or higher, or GCC for  Solaris  Systems	4.2.0  or
     higher,  on a machine with	Solaris	10 update 6 or higher (or
     Oracle   Solaris	11   Express).	 On   older   OSes    try
     -xbinopt=prepare  flag (SPARC platforms only).  Using the -g
     option allows Discover to produce more informative	messages.


MESSAGES

     Discover may produce the following	error messages:

	  ERROR	(UAR) reading from unallocated memory
	  ERROR	(UAW) writing to unallocated memory
	  ERROR	(FMR) reading from freed memory
	  ERROR	(FMW) writing to freed memory
	  ERROR	(UMR) accessing	uninitialized data
	  ERROR	(PIR) accessing	partially initialized data
	  ERROR	(ABR) reading memory beyond array bounds
	  ERROR	(ABW) writing to memory	beyond array bounds
	  ERROR	(DFM) double freeing memory
	  ERROR	(BFM) freeing wrong memory block
	  ERROR	(BRP) bad address parameter for	realloc
	  ERROR	(SBR) read is beyond current stack bounds
	  ERROR	(SBW) write is beyond current stack bounds
	  ERROR	(IMR) read from	invalid	memory address
	  ERROR	(IMW) write to invalid memory address
	  ERROR	(FRP) freed pointer passed to realloc
	  ERROR	(CGB) corrupted	array guard block
	  ERROR	(OLP) overlapping source and destination
	  WARNING (AZS)	allocating zero	size memory block
	  WARNING (NAR)	non-annotated read
	  WARNING (NAW)	non-annotated write
	  WARNING (SMR)	speculative memory read
	  WARNING (UFR)	unknown	stack frame read
	  WARNING (UFW)	unknown	stack frame write
	  WARNING (USR)	unknown	status while reading
	  WARNING (USW)	unknown	status while writing



OPTIONS

     The following options are supported:

     -?	or -h
	  Print	help message.

     -a	  Write	error data to binary_name.analyze/dynamic  direc-
	  tory for use by the Code Analyzer.

     -b	browser
	  Start	web browser browser automatically  while  running
	  the instrumented program (off	by default).

     -c	[- | lib | file]
	  Check	for errors in all libraries, or	in lib,	or in the
	  libraries  listed (separated by new lines) in	file. The
	  default is to	not check for errors in	libraries.

     -D	dir
	  Cache	Directory. The default is $HOME/SUNW_Bit_Cache.

     -e	n Show only n memory errors in	the  report  (default  is
	  show all errors).

     -E	n Show only n memory leaks in the report (default is 100)

     -f	  Show offsets in the report (hidden by	default).

     -F	[parent	| child]
	  Determines what happens if a binary  you  have  instru-
	  mented with Discover forks while you are running it. By
	  default, Discover continues to  collect  memory  access
	  error	 data  from  the parent	process. If you	want Dis-
	  cover	to follow the fork and collect memory access data
	  from the child process, specify -F child.

     -H	html_file
	  Output analysis to HTML file.	 If html_file is a  rela-
	  tive	pathname,  it  is  placed relative to the working
	  directory where the instrumented binary is run. If  the
	  file	name  contains	%p,  it	will be	replaced with the
	  process id. See -w for more details.

     -i	  Instrument for data race detection. See  Oracle  Studio
	  Thread Analyzer documentation.

     -k	  Force	reinstrumentation.

     -K	  Do not read the bit.rc initialization	files.

     -l	  Run Discover in light	 mode.	Provides  faster  program
	  execution,  but  the	number of detected errors is lim-
	  ited.	The input binary does not have	to  be	specially
	  prepared.

     -m	  Show mangled names in	the report (hidden by default).

     -n	  Do not check for errors in executables. The default  is
	  to check for errors in  executables.

     -N	lib
	  Ignore lib.

     -o	file
	  Instrumented output filename.

     -s	  OK if	dependent libraries are	not instrumentable.

     -S	n Show only n stack frames in the report (default is 8).

     -T	  Do not instrument libraries at run time.

     -v	  Verbose.

     -V	  Print	version	and exit without any further processing.

     -w	txt_file
	  Write	Discover  analysis  to	text  file  (use  "-"  to
	  specify  stderr).   If txt_file is a relative	pathname,
	  it is	placed relative	to the	working	 directory  where
	  the instrumented binary is run. Discover users can make
	  the file name	unique for processes by	asking	the  dis-
	  cover	 runtime to add	the process id to the name of the
	  file.	This can be done by adding a  %p  string  to  the
	  file	name.  For  instance,  -w report.%p.txt	flag will
	  generate a file report.<process_id>.txt. If  there  are
	  multiple %p macros in	the file name, only the	first one
	  will be replaced.

     Discover can generate either a text  report,  using  the  -w
     txtfile  option,  or  an HTML report, using the -H	html_file
     option, or	both, if both options are used.
     If	neither	option is used,	the default  output  is	 an  html
     file,  outfile.html,  where  outfile  is the basename of the
     instrumented output file. The file	is placed in the  working
     directory where the instrumented binary is	run.



EXIT STATUS

     The following exit	values are returned:

     0	     All input files were output successfully.

     1	     An	error occurred.


ENVIRONMENT VARIABLES

     SUNW_DISCOVER_OPTIONS
	  The runtime behavior	of  instrumented  binary  can  be
	  changed  by setting this environment variable	to a list
	  of discover flags (-a, -b, -e, -E, -f, -F, -H, -l,  -L,
	  -m, -S, -w).	For instance, if the user wants	to change
	  the number of	errors reported	to 50 and limit	the stack
	  depth	in the report to 3, setting SUNW_DISCOVER_OPTIONS
	  should be set	to "-E 50 -S 3".


EXAMPLES

  EXAMPLE #1
     By	default	Discover sends output to an HTML file.

	  % cat	dtest_2.c
	  #include <stdio.h>
	  #include <stdlib.h>
	  int main(int argc, char *argv[])
	  {
	      char *cp;
	      cp = (char *)malloc(10);
	      cp[11] = 't';
	      return 0;
	  }

	  % cc -g -O1 -o dtest_2.prep dtest_2.c
	  % discover -o	dtest_2.disc dtest_2.prep
	  % ./dtest_2.disc
	  % ls
	  dtest_2.c
	  dtest_2.prep*
	  dtest_2.disc*
	  dtest_2.disc.html

     Notice that Discover did not print	messages but generated an
     HTML  file	that provides a	summary	and an easy-to-use click-
     for-details interface.


  EXAMPLE #2
     We	use the	same program as	in example #1, but "-w -"  option
     to	output report in text format to	stderr.

	  % discover -w	- -o dtest_2.disc dtest_2.prep
	  % ./dtest_2.disc
	  ERROR	(ABW): writing to memory beyond	array bounds at	address	0x50013	(1 byte) at:
	       main() +	0x138  <dtest_2.c:7>
		     4:	   {
		     5:	       char *cp;
		     6:	       cp = (char *)malloc(10);
		     7:=>      cp[11] =	't';
		     8:	       return 0;
		     9:	   }
	       _start()	+ 0x108
	      block at 0x50008 (10 bytes long) was allocated at:
	       malloc()	+ 0x260
	       main() +	0x94  <dtest_2.c:6>
		    3:	  int main(int argc, char *argv[])
		    4:	  {
		    5:	      char *cp;
		    6:=>      cp = (char *)malloc(10);
		    7:	      cp[11] = 't';
		    8:	      return 0;
		    9:	  }
	       _start()	+ 0x108

	  ***************** Discover Memory Report *****************

	  1 block at 1 location	left allocated on heap with a total size of 10 bytes

	      1	block with total size of 10 bytes
	       malloc()	+ 0x260
	       main() +	0x94  <dtest_2.c:6>
		    3:	  int main(int argc, char *argv[])
		    4:	  {
		    5:	      char *cp;
		    6:=>      cp = (char *)malloc(10);
		    7:	      cp[11] = 't';
		    8:	      return 0;
		    9:	  }
	       _start()	+ 0x108

	  DISCOVER SUMMARY:
	       unique errors   : 1 (1 total, 0 filtered)
	       unique warnings : 0 (0 total, 0 filtered)

  EXAMPLE #3
     This example examines a program that contains a use of unin-
     itialized data:


	  % cat	dtest_3.c
	  #include <stdio.h>
	  #include <stdlib.h>
	  int main(int argc, char *argv[])
	  {
	      char s[10];
	      printf("s[1] = %d\n",s[1]);
	      return 0;
	  }

	  % cc -g -O1 -o dtest_3.prep dtest_3.c
	  % ./dtest_3.prep
	  s[1] = 5

	  % discover -w	- -o dtest_3.disc dtest_3.prep
	  % ./dtest_3.disc
	  ERROR	(UMR): accessing uninitialized data from address 0xffbff023 (1 byte) at:
		  main() + 0x4c	[dtest_3.disc:0x3004c]
		    <dtest_3.c:7>:
			   4:	 int main(int argc, char *argv[])
			   5:	 {
			   6:	     char s[10];
			   7:=>	     printf("s[1] = %d\n",s[1]);
			   8:	     return 0;
			   9:	 }
			  10:
		  _start() + 0x108 [dtest_3.disc:0x107cc]
	  s[1] = 5

	  ***************** Discover Memory Report *****************
	  No allocated memory left on program exit.
	  DISCOVER SUMMARY:
		  unique errors	  : 1 (1 total)
		  unique warnings : 0 (0 total)


REQUIREMENTS

     Operating System Requirements
	  The Discover software	 works	on  Solaris  versions  10
	  update 6 or higher and Oracle	Solaris	11 Express.

     Compiler Requirements
	  Discover software works  only	 with  binaries	 compiled
	  with	Sun  Studio  12	Update 1 compiler, Oracle Solaris
	  Studio 12.2, or higher,  or  GCC  for	 Solaris  Systems
	  (GCCFSS)  compiler starting with version 4.2.0.  If you
	  try to run Discover on a binary that is not compiled as
	  stated  above,  Discover  issues  an error and does not
	  instrument the binary.  Using	the -g option when build-
	  ing  the binary is strongly recommended.  If you do not
	  use the -g option, Discover  does  not  display  source
	  code	and line number	information when reporting errors
	  and  warnings.   Instead  it	just   displays	  program
	  counters(PCs)	  of   the  corresponding  machine  level
	  instructions,	which might not	 be  as	 helpful.   Also,
	  using	the -g option helps the	Discover software produce
	  more accurate	results.


FILES

  DISCOVER AND BIT .rc FILES
     Discover initializes its state by reading a  series  of  .rc
     files	 at	  startup.	 A	system	    file,
     <compiler_area>/prod/lib/postopt/bit.rc,  provides	  default
     values  for  certain  variables.  Discover	 reads	this file
     first, then $HOME/.bit.rc,	if it exists, then `pwd`/.bit.rc,
     if	it exists.

     The .rc files contain commands to set, append to, and remove
     from variables. Whenever a	set command is seen, the previous
     value of the variable (if any) is discarded. An append  com-
     mand  causes  its	argument  to  be  appended (after a colon
     separator)	to the existing	value of the variable.	A  remove
     command  causes  its  argument  to	 be removed (along with	a
     colon separator) from the existing	value of the variable.

     The variables set in the  .rc  files  include  the	 list  of
     libraries	to ignore while	instrumenting, and lists of func-
     tions or function prefixes	to ignore when computing the per-
     centage of	nonannotated code in a binary.

     For more information, see the header in the system	.rc file.


SEE ALSO

     bit(1), CC(1), cc(1), f77(1), f90(1), f95(1),  gcc(1)  code-
     analyzer(1).