rsysc: Release storage from the system heap

This function releases storage from the system heap, and returns the 4 KB frames to the pool of available frames.

Last updated

Changed for PUT11 (information only; no code change).

Format

#include <tpf/sysapi.h>
int rsysc(void *address, int frames, char *token);
address
This argument specifies the address of the storage to be released from the system heap.
frames
This argument specifies the number of 4 KB frames to be released.
token
This argument specifies a pointer to the string that was specified when the storage was acquired.

Normal return

RSYSC_OK indicates that the storage is released successfully.

Error return

If the function was passed an incorrect address, number of frames, or token, error code RSYSC_ERROR is returned and no storage is released.

Programming considerations

  • Any storage that is acquired by gsysc() must be returned by the application using rsysc() because the storage is not attached to the ECB and will not be returned when the ECB exits.
  • Storage acquired by gsysc() is tagged with the string specified by the token parameter. You must specify the same string when you release the storage using rsysc().
  • The application that acquires system heap storage needs to save the starting address of the storage, the number of frames allocated, and the token specified.
  • You can use the rsysc or tpf_rsysc function to release system heap; however, the tpf_rsysc function offers more functionality.

Examples

The following example allocates and releases 12 KB of system heap storage. 
#include <tpf/sysapi.h>
#include <stdio.h>
⋮
{
    /******************************************************************/
    /* Allocate 12 KB of storage for a table used by many different   */
    /* ECBs.                                                          */
    /******************************************************************/
    int  frames, rc;
    char * token = "TABLE40 ";
    struct table {
        char  *name;
        int   code;
    } *tbl_ptr;

    frames = 3;
    tbl_ptr = gsysc(frames, token);
    if (tbl_ptr == 0) {
         serrc_op(SERRC_EXIT, 0x1111, "Error allocating table.", NULL);
    }
⋮
    rc = rsysc((void *)tbl_ptr, frames, token);
    if (rc == RSYSC_ERROR) {
         serrc_op(SERRC_EXIT, 0x2222, "Error releasing storage.", NULL);
    }
}