myrealloc: Change reserved storage block size

Use this function to change the size of a reserved block of 31-bit ECB heap storage that is allocated by using the mycalloc, mymalloc, or myrealloc function.

The content of the reserved storage is unchanged. If the block size is increased, the content of additional reserved storage is unknown. The reserved storage is aligned for any type of object.

Last updated

Added for PUT12.

Format

#include <tpf/c_mymalloc.h>
void *myrealloc(void *ptr, int size);
ptr
A pointer to the reserved ECB heap block. If this pointer is NULL, the function reserves a new block of ECB heap storage with the size that the size parameter specifies.
size
The new size of the storage block in bytes.

Normal return

Returns a pointer to the reallocated area of 31-bit ECB heap. The myrealloc function might change the storage location of the block. As a result, the returned value and the value of the ptr parameter might be different.
Notes:
  • If the ptr parameter points to a valid 31-bit ECB heap block and the value that is specified for the size parameter is 0, the 31-bit ECB heap block is released, and a NULL value is returned.
  • If the myrealloc function is called with the ptr parameter specified as NULL, the myrealloc function is processed as the mymalloc function for the specified size.

Error return

The following error conditions might occur:
  • When available storage is not enough to expand the original block of 31-bit ECB heap to the size that the size parameter specifies, the myrealloc function returns a NULL value. The original storage block is unchanged.
  • If the ptr parameter does not specify a pointer that the mycalloc or mymalloc function created, the realloc function is called for this address.
  • If the ptr parameter points to 31-bit ECB heap that was released, the z/TPF system issues a system error, and the ECB exits.

Programming considerations

  • Use the myfree function to return the storage.
  • You can retrieve only 31-bit ECB heap storage by using the myrealloc function.
  • If the request size is not supported in the myrealloc function call, the realloc function is called instead.
  • ECB heap guard x'FFFFFFFF FFFFFFFF' is not put at the end of a mymalloc ECB heap buffer.
  • You cannot create tagging information to be associated with mymalloc buffers. Therefore, you cannot call the tpf_eheap_tag function for a mymalloc buffer.
  • For an ECB in a threaded environment, if a mymalloc API is called, the corresponding malloc API is called instead.
  • If the heap check mode is active and a mymalloc API is called, the corresponding malloc API is called instead.
  • If the ZSTRC command is entered with the NOMYMALLOC parameter specified, when a mymalloc API is called, the corresponding malloc API is called instead.
  • Diagnostic information does not exist for mymalloc calls.
    • ECB heap trace does not track mymalloc calls.
    • For an ECB heap buffer that was obtained by using mymalloc APIs, the dump information does not contain the name of the program that obtained the ECB heap buffer, or the displacement in the program where the request for ECB heap buffer was made.

Examples

The following example shows how to allocate and initialize an array from the 31-bit ECB heap and change the size of the array.
#include <stdio.h>
#include <stdlib.h>
#include <tpf/tpfapi.h>
#include <tpf/c_mymalloc.h>

int main(void)
{
  long * array;                          /* start of the array        */
  long * index;                          /* index variable            */
  int i;                                 /* index variable            */
  int num1 = 5;                          /* number of entries in array*/
  int num2 = 6;                          /* number of entries in array*/

  /* allocate num1 entries using mymalloc() */
  if ( (array = (long *)mymalloc( num1 * sizeof( long ))) != NULL
  {
    for ( ptr = array, i = 0; i < num1; ++i )  /* assign values */
      *ptr++ = i;
  }

  else { /* mymalloc error */
    printf ( "Out of storage\n" );
    abort();
  }

  /* Change the size of the array ... */
  if ( (array = (long *) realloc64( array, num2* sizeof( long )))
      != NULL )
  {
    /* assign values to new elements  */
    for ( ptr = array + num1, i = num1; i <= num2; ++i)
      *ptr++ = i + 2000; 
  }

  else { /* myrealloc error  */
    printf( "Out of storage\n" );
    abort();
  }

}