Command Reference

check|uncheck

All forms of the check and uncheck commands are described below.

The check command prints the current status of RTC

---

check

---

:

To turn on access checking:

---

check -access

---

To turn on leak checking:

---

check -leaks [-frames n
] [-match m]

---

-frames n	Up to n distinct stack frames are displayed when showing the allocation trace of the leaked block.
-match m	Used for combining leaks; if the call stack at the time of allocation for two or more leaks matches m frames, then these leaks are reported in a single combined leak report.

The default value of n is 8 or the value of m (whichever is larger), with a maximum value of 16. The default value of m is 2.

The command check -memuse implies check -leaks. In addition to a leak report at the program exit, you also get a memory use report. At any time during program execution, you can see where all the memory in the program has been allocated.

---

check -memuse [-frames n
] [-match m]

---

To turn on memory use checking:

-frames n

Up to n distinct stack frames are listed when showing the allocation trace of the block in use.

-match m

There may be many blocks in use in the program, so RTC automatically combines the blocks allocated from the same execution trace into one report. The decision to combine the report is controlled by value of m. If the call stack at the allocation of two or more blocks matches m frames, then these blocks are reported in a combined block in use report. The way that blocks are combined is similar to the method used in a leak report.

The default value of n is 8 or the value of m (whichever is larger), with a maximum value of 16. The default value of m is 2.

These two commands are equivalent:

---

check -all [-frames n
] [-match m]
check -access ; check -memuse [-frames n
] [-match m]

---

To turn off access checking:

---

uncheck -access

---

To turn off leak checking:

---

uncheck -leaks

---

To turn off memory use checking (leak checking is also turned off):

---

uncheck -memuse

---

The following two commands are equivalent:

---

uncheck -all
uncheck -access; uncheck -memuse

---

These two commands are equivalent:

---

uncheck [funcs]
[files] [loadobjects
]
suppress all in funcs
 files loadobjects

---

This command allows you to turn on checking in specific functions, modules, and load objects while leaving it turned off for the rest of the program:

---

check function* file* loadobject*

---

This command is equivalent to:

---

suppress all
unsuppress all in function
* file* loadobject
*

---

The command operates cumulatively. For example, the first three commands are equivalent to the last four commands:

---

check main
check foo
check f.c

suppress all
unsuppress all in main
unsuppress all in foo
unsuppress all in f.c

---

Notice that the suppress all command is only applied once, leaving checking turned on for main, foo, and f.c.

These commands are also equivalent:

---

uncheck function*
 file* loadobject
suppress all in function* file* loadobject*

---

showblock

---

showblock -a addr

---

When memory use checking or memory leak checking is turned on, showblock shows the details about the heap block at address addr. The details include the location of the block's allocation and its size.

showleaks

To report new memory leaks since the last showleaks command:

---

showleaks [-a] [-m m
] [-n num]
[-v]

---

In the default non-verbose case, a one line report per leak record is printed. Actual leaks are reported followed by the possible leaks. Reports are sorted according to the combined size of the leaks.

-a	Shows all leaks generated so far (not just the leaks since the last showleaks command).
-m m	Used for combining leaks; if the call stack at the time of allocation for two or more leaks matches m frames, then the leaks are reported in a single combined leak report. The -m option overrides the global value of m specified with the check command. The default value of m is 2 or the global value last given with check.
-n num	Shows up to num records in the report. Default is to show all records.
-v	Generates verbose output. Default is to show non-verbose output.

showmemuse

This command generates a report showing all blocks of memory in use:

---

showmemuse [-a] [-m m
] [-n num]
[-v]

---

Report the top num blocks-in-use records sorted by size. Only blocks that are new since the last showmemuse command are shown.

-a	Shows all blocks in use so far.
-m m	Used for combining the blocks-in-use reports; if the call stack at the time of allocation for two or more blocks matches m frames, then the blocks are reported in a single combined report. The -m option overrides the global value of m specified with the check command. The default value of m is 2 or the global value last given with check.
-n num	Shows up to num records in the report. Default is to show 20.
-v	Generates verbose output. Default is to show non-verbose output.

When memory use checking is on, at program exit an implicit showmemuse -a -n 20 is performed. You can get a verbose output at the program exit time by using the rtc_biu_at_exit dbxenv variable.

suppress|unsuppress

Some or all files in a load object may not be compiled with the -g switch. This implies that there is no debugging information available for functions that belong in these files. RTC uses some default suppression in these cases.

To get a list of these defaults:

---

{suppress | unsuppress} -d

---

To change the defaults for one load object:

---

{suppress | unsuppress} -d [error type
] [in loadobject]

---

To change the defaults for all load objects:

---

{suppress | unsuppress} -d [error type
]

---

To reset these defaults to the original settings:

---

suppress -reset

---

Use the following command to suppress or unsuppress the most recent error. The command applies only to access errors and not to leak errors:

---

{suppress | unsuppress} -last

---

To display the history of the suppress commands not including the -d and -reset commands:

---

{suppress | unsuppress}

---

Turn error reports on or off for the specified error types for the specified location:

---

{suppress | unsuppress} [error type
... [location_specifier
]]

---

To remove the suppress or unsuppress events as given by the id(s):

---

suppress -r id...

---

To remove all the suppress and unsuppress events as given by suppress:

---

suppress -r [0 | all | -all]

---

Error Type Location Specifier

The following are the error type location specifiers.

in loadobject	All functions in the designated program or library
in file	All functions in file
in function	Named function
at line specifier	At source line
addr address	At hex address

To see a list of the load objects, type loadobjects at the dbx prompt. If the line specifier is blank, the command applies globally to the program. Only one line specifier may be given per command.

RTC Errors

Address in Block (aib)

---

Problem: A possible memory leak. There is no reference to the start of an allocated block, but there is at least one reference to an address within the block.
Possible causes: The only pointer to the start of the block is incremented.
char *ptr;
main()
{
		ptr = (char *)malloc(4);
		ptr++;					/* Address in Block */
}

---

Address in Register (air)

---

Problem: A possible memory leak. An allocated block has not been freed, and no reference to the block exists anywhere in program memory.
Possible causes: All references to an allocated block are contained in registers. This can occur legitimately if the compiler keeps a program variable only in a register instead of in memory. The compiler often does this for local variables and function parameters when optimization is turned on. If this error occurs when optimization has not been turned on, it is likely to be an actual memory leak. This can occur if the only pointer to an allocated block goes out of scope before the block is freed.
		if (i == 0) {
				char *ptr = (char *)malloc(4);
				/* ptr is going out of scope */
		}
	 /* Memory Leak or Address in Register */

---

Bad Free (baf)

---

Problem: Attempt to free memory that has never been allocated.
Possible causes: Passing a non-heap data pointer to 
free() or realloc().
		char a[4];
		char *b = &a[0];

		free(b);					/* Bad free (baf) */

---

Duplicate Free (duf)

---

Problem: Attempt to free a heap block that has already been freed.
Possible causes: Calling free()
 more than once with the same pointer. In C++, using the 
delete operator more than once on the
same pointer.
		char *a = (char *)malloc(1);
		free(a);
		free(a);					/* Duplicate free (duf) */

---

Misaligned Free (maf)

---

Problem: Attempt to free a misaligned heap block.
Possible causes: Passing an improperly aligned pointer
to free() or realloc()
; changing the pointer returned by malloc
.
		char *ptr = (char *)malloc(4);
		ptr++;
		free(ptr);					/* Misaligned free */

---

Misaligned Read (mar)

---

Problem: Attempt to read data from an address without proper alignment.
Possible causes: Reading 2, 4, or 8 bytes from an address that is not half-word-aligned, word-aligned, or double-word-aligned, respectively.
		char *s = "hello world";
		int *i = (int *)&s[1];
		int j;

		j = *i;					/* Misaligned read (mar) */

---

Misaligned Write (maw)

---

Problem: Attempt to write data to an address without proper alignment.
Possible causes: Writing 2, 4, or 8 bytes to an address that is not half-word-aligned, word-aligned, or double-word-aligned, respectively.
		char *s = "hello world";
		int *i = (int *)&s[1];

		*i = 0;					/* Misaligned write (maw) */

---

Memory Leak (mel)

---

Problem: An allocated block has not been freed, and no reference to the block exists anywhere in the program.
Possible causes: Program failed to free a block no longer used.
char *ptr;
    ptr = (char *)malloc(1);
    ptr = 0;
/* Memory leak (mel) */

---

Out of Memory (oom)

---

Problem: Attempt to allocate memory beyond physical memory available.
Cause: Program cannot obtain more memory from the system.
Useful in tracking down problems that occur when the return value
from malloc() is not checked
for NULL, which is a common
programming mistake.
		char *ptr = (char *)malloc(0x7fffffff);
		/* Out of Memory (oom), ptr == NULL */

---

Read from Unallocated Memory (rua)

---

Problem: Attempt to read from nonexistent, unallocated, or unmapped memory.
Possible causes: A stray pointer, overflowing the bounds of a heap block or accessing a heap block that has already been freed.
		char c, *a = (char *)malloc(1);
		c = a[1];					/* Read from unallocated memory (rua) */

---

Read from Uninitialized Memory (rui)

---

Problem: Attempt to read from uninitialized memory.
Possible causes: Reading local or heap data that has not been initialized.
		foo()
		{ 	int i, j;
			j = i;				/* Read from uninitialized memory (rui) */
		}

---

Write to Read-Only Memory (wro)

---

Problem: Attempt to write to read-only memory.
Possible causes: Writing to a text address, writing to
a read-only data section (.rodata
), or writing to a page that has been mmap
'ed as read-only.
		foo()
		{ 	int *foop = (int *) foo;
			*foop = 0;				/* Write to read-only memory (wro) */
		}

---

Write to Unallocated Memory (wua)

---

Problem: Attempt to write to nonexistent, unallocated, or unmapped memory.
Possible causes: A stray pointer, overflowing the bounds of a heap block, or accessing a heap block that has already been freed.
		char *a = (char *)malloc(1);
		a[1] = `\0';					/* Write to unallocated memory (wua) */

---

dbxenv Variables

The following dbxenv variables control the operation of RTC. If you want to permanently change any of these variables from their default values, place the dbxenv commands in the $HOME/.dbxrc file.Then, your preferred values are used whenever you use RTC.

dbxenv rtc_auto_continue {on | off}

rtc_auto_continue on causes RTC not to stop upon finding an error, but to continue running. It also causes all errors to be redirected to the rtc_error_log_file_name.The default is off.

dbxenv rtc_auto_suppress {on | off}

rtc_auto_suppress on causes a particular access error at a particular location to be reported only the first time it is encountered and suppressed thereafter. This is useful, for example, for preventing multiple copies of the same error report when an error occurs in a loop that is executed many times. The default is on.

dbxenv rtc_biu_at_exit {on | off | verbose}

This variable is used when memory use checking is on. If the value of the variable is on, a non-verbose memory use (blocks in use) report is produced at program exit. The default is on.

If the value is verbose, a verbose memory use report is produced at program exit. The value off causes no output. This variable has no effect on the showmemuse command.

dbxenv rtc_error_log_file_name filename

rtc_error_log_file_name redirects RTC error messages to the designated file instead of to the standard output of dbx. The default is /tmp/dbx.errlog.uniqueid.

The program does not automatically stop when run time errors are detected in batch mode. All error output is directed to your rtc_error_log_file_name file. The program stops when breakpoints are encountered or if the program is interrupted.

In batch mode, the complete stack backtrace is generated and redirected to the rtc_error_log_file_name file. To redirect all errors to the terminal, set the rtc_error_log_file_name to /dev/tty.

dbxenv rtc_error_limit n

n is the maximum number of errors that RTC reports. The error limit is used separately for access errors and leak errors. For example, if the error limit is set to 5, then a maximum of five access errors and five memory leaks are shown in both the leak report at the end of the run and for each showleaks command you issue. The default is 1000.

dbxenv rtc_mel_at_exit {on | off | verbose}

This variable is used when leak checking is on. If the value of the variable is on, a non-verbose memory leak report is produced at program exit. If the value is verbose, a verbose memory leak report is produced at program exit. The value off causes no output. This variable has no effect on the showleaks command. The default is on.