NAME
_rtc_check_free, _rtc_check_malloc, _rtc_check_realloc,
_rtc_check_malloc_result, _rtc_check_realloc_result,
_rtc_hide_region, _rtc_off, _rtc_on, _rtc_record_free,
_rtc_record_malloc, _rtc_record_realloc, _rtc_report_error,
rtc_api - Runtime Checking (RTC) API for the use of private
memory allocators.
SYNOPSIS
#include <rtc_api.h>
RTC_Result _rtc_check_free(void *ptr);
RTC_Result _rtc_check_malloc(size_t size);
RTC_Result _rtc_check_realloc(void *ptr, size_t size);
RTC_Result _rtc_check_malloc_result(void *ptr, size_t size);
RTC_Result _rtc_check_realloc_result(void *old_ptr, void
*new_ptr, size_t new_size);
RTC_Result _rtc_hide_region(void *ptr, size_t size);
RTC_Result _rtc_off(void );
RTC_Result _rtc_on(void );
RTC_Result _rtc_record_free(void *ptr);
RTC_Result _rtc_record_malloc(void *ptr, size_t size);
RTC_Result _rtc_record_realloc(void *old_ptr, void *new_ptr,
size_t new_size);
void _rtc_report_error(RTC_Result err);
MT-LEVEL
MT-Safe
DESCRIPTION
Runtime Checking (RTC) requires that the standard heap
management routines in the shared library libc.so be used so
that RTC can keep track of all the allocation and dealloca-
tions in the program. Many applications write their own
memory management routines either on top of malloc-free or
from scratch. When you use your own, known as private,
allocators, RTC cannot automatically track them. However,
RTC provides an API for the use of private allocators which
allows them to to be treated the same as the standard heap
allocators.
Runtime Checking API functions provide an interface for con-
veying the use of non-standard memory allocators to RTC.
This interface supports malloc, free, and realloc as if they
were private memory allocators, which can use the API func-
tions to update RTC's memory maps when it allocates and
frees memory regions. The API enables RTC to check memory
accesses made by programs that use the allocator.
Some minor differences may exist with RTC error reporting
when "private allocators" do not use the program heap. When
memory access errosr referring a standard heap block occurs,
an RTC error report typically includes the location of the
heap block allocation. This may not be reported in such
cases.
All entry points in the RTC API are macros which turn into
calls to appropriate functions in the RTC library when run-
ning under RTC. You don't need to compile the code condi-
tionally to use them.
_rtc_check_free() - called to see if the argument passed to
the free-like function is valid.
_rtc_check_malloc() - called to see if the arguments passed
to the malloc-like function are valid.
_rtc_check_realloc() - called to see if the argument passed
to the realloc-like function is valid.
_rtc_check_malloc_result() - called to see if the pointer,
'ptr', produced as a result of allocating 'size' bytes is a
valid result of a malloc-like function.
_rtc_check_realloc_result() - called to see if the pointer,
'new_ptr', produced as a result of re-allocating 'old_ptr'
to 'size' bytes is a valid result of the realloc-like func-
tion.
_rtc_hide_region() - marks 'size' bytes starting at 'ptr' as
inaccessible on the RTC memory map. Used to invalidate
accesses to memory acquired with sbrk() or mmap() that will
be allocated on demand.
_rtc_off() and _rtc_on() - enables private allocators to
shut off memory access checking while manipulating data
structures in memory regions that RTC considers inaccess-
able. An allocator can turn off checking by calling
_rtc_off() before accessing such a memory region, and cal-
ling _rtc_on() to turn checking back on when finished.
_rtc_record_free(), _rtc_record_malloc(), and
_rtc_record_realloc() - changes RTC's memory maps to reflect
changes in the accessability of memory regions that occur
when the private allocator allocates and frees blocks of
memory.
_rtc_report_error() - reports errors.
RETURN VALUES
In cases where the operation was successful,
_rtc_check_free, _rtc_check_malloc, _rtc_check_realloc,
_rtc_check_malloc_result, _rtc_check_realloc_result,
_rtc_hide_region, _rtc_record_free, _rtc_record_malloc and
_rtc_record_realloc all return RTC_SUCCESS. When unsuccess-
ful, they return an error result which can be passed to
_rtc_report_error.
EXAMPLES
These example calls to the RTC API functions illustrate how
they enable a private memory allocator to keep RTC's memory
maps current.
1. Acquire memory for later allocation:
{
size_t large_block = size_needed;
void *old_break_ptr = sbrk((int)large_block);
RTC_Result result;
result = _rtc_hide_region(old_break_ptr, large_block);
if (result != RTC_success)
return NULL;
return old_break_ptr;
}
2. Allocate a block (malloc-like function):
{
size_t block_size = request_size;
void *ptr = NULL;
RTC_Result result = RTC_SUCCESS;
result = _rtc_check_malloc(block_size);
if (result == RTC_SUCCESS) {
_rtc_off();
ptr = private_alloc(block_size);
_rtc_on();
result = _rtc_record_malloc(ptr, block_size);
if (result == RTC_SUCCESS) {
/* If we had guard blocks around the block of memory
* we would return to the user then we would mark
* the guard blocks as inaccessible by using
* _rtc_hide_region()
*/
}
}
if (result != RTC_SUCCESS)
_rtc_report_error(result);
return ptr;
}
3. Free a block (free-like function):
{
RTC_Result result = RTC_SUCCESS;
result = _rtc_check_free(ptr);
if (result == RTC_SUCCESS) {
_rtc_off();
private_free(ptr);
_rtc_on();
(void)_rtc_record_free(ptr);
} else {
_rtc_report_error(result);
}
}
4. Reallocate a block (realloc-like function):
{
void *new_ptr = NULL;
size_t size = request_size;
void *old_ptr;
RTC_Result result = RTC_SUCCESS;
result = _rtc_check_realloc(old_ptr, size);
if (result == RTC_SUCCESS) {
_rtc_off();
new_ptr = private_realloc(old_block_record, size);
_rtc_on();
result = _rtc_check_realloc_result(old_ptr, new_ptr, size);
if (result == RTC_SUCCESS)
result = _rtc_record_realloc(old_ptr, new_ptr, size);
}
if (result != RTC_SUCCESS)
_rtc_report_error(result);
return new_ptr;
}
SEE ALSO
dbx(1), mmap(2), sbrk(2)