.\" @(#)rtc_api.3x 1.2 96/09/04 SMI; .TH rtc_api 3x "09/04/96" .SH 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. .SH SYNOPSIS .LP .B #include .LP .BI "RTC_Result _rtc_check_free(void *" ptr ); .LP .BI "RTC_Result _rtc_check_malloc(size_t " size ); .LP .BI "RTC_Result _rtc_check_realloc(void *" ptr , .BI "size_t " size ); .LP .BI "RTC_Result _rtc_check_malloc_result(void *" ptr , .BI "size_t " size ); .LP .BI "RTC_Result _rtc_check_realloc_result(void *" old_ptr , .BI "void *" new_ptr , .BI "size_t " new_size ); .LP .BI "RTC_Result _rtc_hide_region(void *" ptr , .BI "size_t " size ); .LP .BI "RTC_Result _rtc_off(void );" .LP .BI "RTC_Result _rtc_on(void );" .LP .BI "RTC_Result _rtc_record_free(void *" ptr ); .LP .BI "RTC_Result _rtc_record_malloc(void *" ptr , .BI "size_t " size ); .LP .BI "RTC_Result _rtc_record_realloc(void *" old_ptr , .BI "void *" new_ptr , .BI "size_t " new_size ); .LP .BI "void _rtc_report_error(RTC_Result " err ); .SH MT-LEVEL .LP MT-Safe .SH 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 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. .LP .B _rtc_check_free(\|) - called to see if the argument passed to the free-like function is valid. .LP .B _rtc_check_malloc(\|) - called to see if the arguments passed to the malloc-like function are valid. .LP .B _rtc_check_realloc(\|) - called to see if the argument passed to the realloc-like function is valid. .LP .B _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. .LP .B _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. .LP .B _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. .LP .B _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. .LP .B _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. .LP .B _rtc_report_error(\|) - reports errors. .LP .SH "RETURN VALUES" .LP 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. .SH EXAMPLES These example calls to the RTC API functions illustrate how they enable a private memory allocator to keep RTC's memory maps current. .LP .RS .ft 1 .nf 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; } .fi .ft .RE .LP .RS .ft 1 .nf 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; } .fi .ft .RE .LP .RS .ft 1 .nf 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); } } .fi .ft .RE .LP .RS .ft 1 .nf 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; } .fi .ft .RE .LP .SH "SEE ALSO" .BR dbx (1), .BR mmap (2), .BR sbrk (2)