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