You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR Reference
Previous     Contents     Next     

Chapter 15   Memory Management Operations

This chapter describes the global functions and macros you use to perform memory management. NSPR provides heap-based memory management functions that map to the familiar malloc, calloc, realloc, and free.

Memory Allocation Functions
Memory Allocation Macros

Memory Allocation Functions

NSPR has its own heap, and these functions act on that heap. Libraries built on top of NSPR, such as the Netscape security libraries, use these functions to allocate and free memory. If you are allocating memory for use by such libraries or freeing memory that was allocated by such libraries, you must use these NSPR functions rather than the libc equivalents.

Memory allocation functions are:

PR_Malloc
PR_Calloc
PR_Realloc
PR_Free

PR_Malloc, PR_Calloc, PR_Realloc, and PR_Free have the same signatures as their libc equivalents malloc, calloc, realloc, and free, and have the same semantics. (Note that the argument type size_t is replaced by PRUint32.) Memory allocated by PR_Malloc, PR_Calloc, or PR_Realloc must be freed by PR_Free.

PR_Malloc

Allocates memory of a specified size from the heap.


Syntax 
#include <prmem.h>


void * PR_Malloc (PRUint32 size);


Parameter
This function has the following parameter:

size

Size in bytes of memory to be allocated.


Returns
An untyped pointer to the allocated memory, or if the allocation attempt fails, NULL. Call PR_GetError to retrieve the error returned by the libc function malloc.


Description
This function allocates memory of the requested size from the heap. 

PR_Calloc

Allocates zeroed memory from the heap for a number of objects of a given size.


Syntax 
#include <prmem.h>


void *PR_Calloc (
   PRUint32 nelem, 
   PRUint32 elsize);


Parameter
This function has the following parameters:

nelem 

The number of elements of size elsize to be allocated.

elsize 

The size of an individual element.


Returns
An untyped pointer to the allocated memory, or if the allocation attempt fails, NULL. Call PR_GetError to retrieve the error returned by the libc function calloc.


Description
This function allocates memory on the heap for the specified number of objects of the specified size. All bytes in the allocated memory are cleared. 

PR_Realloc

Resizes allocated memory on the heap.


Syntax 
#include <prmem.h>


void *PR_Realloc (
   void *ptr, 
   PRUint32 size);


Parameter
This function has the following parameters:

ptr 

A pointer to the existing memory block being resized.

size 

The size of the new memory block.


Returns
An untyped pointer to the allocated memory, or if the allocation attempt fails, NULL. Call PR_GetError to retrieve the error returned by the libc function realloc.


Description
This function attempts to enlarge or shrink the memory block addressed by ptr to a new size. The contents of the specified memory remains the same up to the smaller of its old size and new size, although the new memory block's address can be different from the original address. 

PR_Free

Frees allocated memory in the heap.


Syntax 
#include <prmem.h>


void PR_Free(void *ptr);


Parameter
This function has the following parameter:

ptr 

A pointer to the memory to be freed.


Returns
Nothing.


Description
This function returns the memory addressed by ptr to the heap. 

Memory Allocation Macros

Macro versions of the memory allocation functions are available, as well as additional macros that provide programming convenience:

PR_MALLOC
PR_NEW
PR_REALLOC
PR_CALLOC
PR_NEWZAP
PR_DELETE
PR_FREEIF

PR_MALLOC

Allocates memory of a specified size from the heap.


Syntax 
#include <prmem.h>


void * PR_MALLOC(_bytes);


Parameter
This macro has the following parameter:

_bytes 

Size of the requested memory block.


Returns
An untyped pointer to the allocated memory, or if the allocation attempt fails, NULL. Call PR_GetError to retrieve the error returned by the libc function malloc.


Description
This macro allocates memory from the heap. 

PR_NEW

Allocates an instance of the specified type from the heap.


Syntax 
#include <prmem.h>


_type * PR_NEW(_struct);


Parameter
This macro has the following parameter:

_struct

The name of a type.


Returns
A pointer to type _type or NULL on error. Call PR_GetError to retrieve the error returned by the libc function.


Description
This macro allocates memory whose size is sizeof(_struct) and returns a pointer to that memory. 

PR_REALLOC

Resizes allocated memory from the heap.


Syntax 
#include <prmem.h>


void * PR_REALLOC(_ptr, _size);


Parameter
This macro has the following parameters:

_ptr 

pointer of memory to be re-sized.

_size 

The requested new size.


Returns
An untyped pointer to the resized memory, or if the allocation attempt fails, NULL. Call PR_GetError to retrieve the error returned by the libc function realloc.


Description
This macro re-allocates memory at the specified location and sets its size to the specified number of bytes. It behaves exactly like PR_Realloc.

PR_CALLOC

Allocates and clears memory of a given size from the heap.


Syntax 
#include <prmem.h>


void * PR_CALLOC(_size);


Parameter
This macro has the following parameter:

_size 

The size of memory to be allocated.


Returns
An untyped pointer to the allocated memory, or if the allocation attempt fails, NULL. Call PR_GetError to retrieve the error returned by the libc function calloc.


Description
This macro allocates a block of memory of the specified size from the heap and clears the memory. 

PR_NEWZAP

Allocates and clears memory from the heap for an instance of a given type.


Syntax 
#include <prmem.h>


(_type *) PR_NEWZAP(_struct);


Parameter
This macro has the following parameter:

_struct

The name of a type.


Returns
A pointer to memory of size sizeof(_type) whose contents are set to zero, or NULL on error. Call PR_GetError to retrieve the error returned by the libc function.


Description
This macro allocates an instance of the specified type from the heap and sets the content of that memory to zero. 

PR_DELETE

Frees allocated memory in the heap.


Syntax 
#include <prmem.h>


void PR_DELETE(_ptr);


Parameter
This macro has the following parameter:

_ptr 

The address of memory to be returned to the heap. Must be an lvalue (an expression that can appear on the left side of an assignment statement).


Returns
Nothing. 


Description
This macro returns allocated memory to the heap from the specified location and sets _ptr to NULL.

PR_FREEIF

Conditionally frees allocated memory.


Syntax 
#include <prmem.h>


void PR_FREEIF(_ptr);


Parameter
This macro has the following parameter:

_ptr 

The address of memory to be returned to the heap.


Returns
Nothing.


Description
This macro returns memory to the heap when _ptr is not NULL. If _ptr is NULL, the macro has no effect. 

Previous     Contents     Next     

Last Updated May 18, 2001