digitalmars.com                      
Last update Thu Jun 16 18:50:48 2011

handle.h


handle_calloc

Header
handle.h
Prototype
void __handle *handle_calloc(unsigned size);
Description
The handle_calloc function allocates and clears a block of data, size bytes long, from handle (EMS) memory. If you use this function to allocate handle memory, you must use handle_ functions to manage this memory.

The handle_calloc function returns a __handle pointer that 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. 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.

Note
If handle (EMS) memory is not present in the host system the _handle functions act as if NO_HANDLE is defined. This also occurs when the X, P, or N memory models are used.
Return Value
A __handle pointer to the allocated memory.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
handle_malloc handle_free handle_realloc

handle_free

Header
handle.h
Prototype
void handle_free(void __handle *hptr);
Description
The handle_free function frees the memory pointed to by the __handle pointer hptr, that was previously allocated by handle_malloc or handle_calloc.
Return Value
None
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
handle_calloc handle_malloc
Example
See handle_malloc

handle_ishandle

Header
handle.h
Prototype
int handle_ishandle(void __handle *hptr);
Description
The handle_ishandle function tests whether hptr is a true __handle pointer or a far pointer. If there is no handle memory present, __handle pointers default to being normal pointers.
Return Value
Returns 1 if hptr is a __handle pointer; otherwise returns 0.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
handle_malloc
Example
See handle_malloc

handle_malloc

Header
handle.h
Prototype
void __handle *handle_malloc(unsigned size);
Description
The handle_malloc function allocates a block of handle (EMS) memory of size bytes from handle space. When you use handle_malloc to allocate handle memory, you must use handle_functions to manage this memory.

The handle_malloc function returns a __handle pointer that 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. 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.

Note
If handle (EMS) memory is not present in the host system the _handle functions act as if NO_HANDLE were defined. This also occurs when the X or P memory models are used.
Return Value
A __handle pointer to the allocated memory.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
handle_calloc handle_free handle_malloc
Example
/* Example for handle_malloc */

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

/* C and L models ONLY */

void 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");
}

handle_realloc

Header
handle.h
Prototype
void __handle *handle_realloc(void __handle
*hptr, unsigned nbytes);
Description
The handle_realloc function reallocates (changes the size of) a block of memory that was allocated by handle_malloc or handle_calloc.
Return Value
A __handle pointer to the reallocated data block.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
handle_calloc handle_malloc
Example
See handle_malloc

handle_strdup

Header
handle.h
Prototype
char __handle *handle_strdup(char __handle *hptr);
Description
The handle_strdup function uses handle_malloc to allocate a block of memory in handle space, and then makes a copy of the string pointed to by the __handle pointer hptr in the allocated memory.
Return Value
A __handle pointer to the duplicated string.
Compatibility
DOS Windows 3.x Phar Lap DOSX Win32
See Also
handle_malloc
Example
See handle_malloc
Home | Compiler & Tools | IDDE Reference | STL | Search | Download | Forums