#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-Safe
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 deallocations 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 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 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 function.
_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(2) or mmap(2) 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 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.
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().
These example calls to the RTC API functions illustrate how they enable a private memory allocator to keep RTC's memory maps current.
Example 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;
}
Example 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;
}
Example 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);
}
}
Example 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;
}
dbx(1), mmap(2), sbrk(2)