Man Page _rtc_check_realloc.3x




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)