Name
malloc, _fmalloc, _nmalloc - Allocate main memory.
Syntax
#include <stdlib.h>
#include <malloc.h>
void *malloc(size)
void far *_fmalloc(size)
void near *_nmalloc(size)
size_t size;
Description
The malloc family of functions allocates a memory block of
at least size bytes. (The block may be larger than size
bytes because of space required for alignment and for
maintenance information.)
If size is 0, malloc allocates a zero-length item in the
heap and returns a valid pointer to that item.
The storage space pointed to by the return value is
guaranteed to be suitably aligned for storage of any type of
object. To get a pointer to a type other than void, use a
type cast on the return value.
In large data models (compact- and large-model programs),
malloc maps to _fmalloc. In small data models (small- and
medium-model programs), malloc maps to _nmalloc.
The _fmalloc function allocates a memory block of at least
size bytes outside the default data segment. (The block may
be larger than size bytes because of the space required for
alignment.) The _fmalloc function returns a far pointer to
void. The storage space pointed to by the return value is
guaranteed to be suitably aligned for storage of any type of
object. To get a pointer to a type other than void, use a
type cast on the return value.
The various malloc functions allocate memory in the heap
specified in the following list:
Function Heap Segment
malloc Depends on data model of program
_fmalloc Far heap (outside default data
segment); see below for description of
_fmalloc allocation retry
_nmalloc Near heap (inside default data segment)
If sufficient memory is not available outside the default
data segment, _fmalloc will retry allocating within the
default data segment. If there is still insufficient memory
available, the return value is NULL.
If you are creating programs to run in both real and
protected mode, you should probably bind with apilmr.obj as
well as api.lib and doscalls.lib. This is necessary in any
cases where a program will use the _nmalloc function.
Return Value
The malloc function returns a void pointer to the allocated
space. Depending on the type of allocation, the pointer may
be a near pointer to void (_nmalloc) or a far pointer to
void (_fmalloc).
The storage space pointed to by the return value is
guaranteed to be suitably aligned for storage of any type of
object. To get a pointer to a type other than void, use a
type cast on the return value.
The _malloc and _nmalloc functions return NULL if there is
insufficient memory available. If _fmalloc does not find
sufficient memory available outside the default data
segment, it will try reallocating inside the default data
segment. If there is still insufficient memory available,
_fmalloc will return NULL.
Always check the return from the malloc function when it is
used under OS/2, even if the amount of memory requested is
small.
See Also
calloc(S), free(DOS), realloc(S)
Example
#include <stdlib.h> /* definition of _MAX_PATH */ #include
<stdio.h> #include <malloc.h>
char *string;
main()
{
/* Allocate space for a pathname */
string = malloc (_MAX_PATH);
if (string == NULL )
printf( "Insufficient memory available\n" );
else
printf( "Memory space allocated for
pathname.\n" );
}
This program uses malloc to allocate space from the heap for
a path name.
(printed 6/18/89)