Click above to get retro games delivered to your door ever month!

The Handle Package

   This package allows the allocation of handle memory to __handle pointers.
   For OS/2 and 32 bit memory models these are equivalent to normal far
   pointers.

   The Handle package is a set of functions which allow the programmer
   dynamically to allocate and use handle memory. Currently the Handle
   package supports EMS (LIMS) memory. Handle memory is manipulated by means
   of a special pointer type, the __handle pointer.The programmer can use
   calls to handle_malloc, handle_calloc, handle_realloc and handle_free to
   allocate memory from handle memory in a similar fashion to the standard
   memory allocation routines.

   The handle allocation functions return a __handle pointer which can, with
   a few restrictions, be used in the same way as any other pointer. A
   special function, handle_strdup, is provided to make a copy of a string
   in handle space. Handle pointers can be used in most situations that a
   far data pointer could be used, for instance as function arguments in the
   compact and large memory models. A __handle pointer should be assigned to
   a normal far pointer before being passed to a formatted print routine.
   Handle memory cannot currently be used for code.


   The use of handle memory can be "locked out" by #defining NO_HANDLE
   before including handle.h, in which case any use of handle pointers and
   functions defaults to normal pointers and memory allocation routines.

   If there is no handle (EMS) memory present in the host system the Handle
   package acts as if NO_HANDLE were defined. This also occurs under OS/2
   and when the Z, X or P memory models are used. For more information on
   __handle pointers please refer to the chapter The Handle Pointer Type in
   the Compiler Reference.

Example

   #include <stdio.h>
   #include <handle.h>
   #include <stdlib.h>

   /* C and L models ONLY */

   int main()
   {

       char __handle *hptr;
       char __handle *cptr;
       char *p;

       hptr = handle_malloc(256);

       if (handle_ishandle(hptr) == 0)
           sprintf(hptr,"This string is in normal memory");
       else
           sprintf(hptr,"This string is in handle memory");
       p = hptr;
       printf("%s - handle pointer is %p\n",p,hptr);
       cptr = handle_strdup(hptr);
       p = cptr;
       printf("%s - this time from %p\n",p,cptr);

       handle_free(hptr);
       handle_free(cptr);
       printf("All Handles freed\n");
       return EXIT_SUCCESS;

   }