rtc_api(3x)rtc_api(3x)NAME
_rtc_check_free, _rtc_check_malloc, _rtc_check_realloc, _rtc_check_mal‐
loc_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 rou‐
tines in the shared library libc.so be used so that RTC can keep track
of all the allocation and deallocations in the program. Many applica‐
tions write their own memory management routines either on top of mal‐
loc-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 conveying 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 functions 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 running under RTC. You
don't need to compile the code conditionally 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 mal‐
loc-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', pro‐
duced 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 function.
_rtc_hide_region() - marks 'size' bytes starting at 'ptr' as inaccessi‐
ble 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 mem‐
ory access checking while manipulating data structures in memory
regions that RTC considers inaccessable. An allocator can turn off
checking by calling _rtc_off() before accessing such a memory region,
and calling _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 unsuccessful, 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 ALSOdbx(1), mmap(2), sbrk(2)
09/04/96 rtc_api(3x)
