NSPR Reference: Chapter 15 Memory Management Operations
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

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