Memory Management Utilities


Functions

void * cpl_calloc (size_t natoms, size_t nbytes)
 Allocate memory for natoms elements of size size.
void cpl_free (void *memblk)
 Memory block deallocation.
void * cpl_malloc (size_t nbytes)
 Allocate nbytes bytes.
void cpl_memory_dump (void)
 Display the memory status.
int cpl_memory_is_empty (void)
 Tell if there is some memory allocated.
void * cpl_realloc (void *memblk, size_t nbytes)
 Change the size of a memory block.
char * cpl_sprintf (const char *format,...)
 Create a string and fill it in an sprintf()-like manner.
char * cpl_strdup (const char *string)
 Duplicate a string.
char * cpl_vsprintf (const char *format, va_list arglist)
 Create a string and fill it in an vsprintf()-like manner.

Detailed Description

This module provides the CPL memory management utilities.

Function Documentation

void* cpl_calloc ( size_t  natoms,
size_t  nbytes 
)

Allocate memory for natoms elements of size size.

Parameters:
natoms Number of atomic elements.
nbytes Element size in bytes.
Returns:
Pointer to the allocated memory block.
The function allocates memory suitable for storage of natoms elements of size nbytes bytes. The allocated memory is cleared, i.e. the value 0 is written to each single byte.

Note:
If the memory subsytem has not been initialised before calling this function, the program execution is stopped printing a message to the error channel showing the current code position.

void cpl_free ( void *  memblk  ) 

Memory block deallocation.

Returns:
Nothing.
Deallocates a memory block previously allocated by any of the CPL allocator functions.

See also:
cpl_malloc(), cpl_calloc()

void* cpl_malloc ( size_t  nbytes  ) 

Allocate nbytes bytes.

Parameters:
nbytes Number of bytes.
Returns:
Pointer to the allocated memory block.
The function allocates nbytes bytes of memory. The allocated memory is not cleared.

Note:
If the memory subsytem has not been initialised before calling this function, the program execution is stopped printing a message to the error channel showing the current code position.

void cpl_memory_dump ( void   ) 

Display the memory status.

int cpl_memory_is_empty ( void   ) 

Tell if there is some memory allocated.

Returns:
-1 if the model is off, 1 if it is empty, 0 otherwise

void* cpl_realloc ( void *  memblk,
size_t  nbytes 
)

Change the size of a memory block.

Parameters:
memblk Pointer to the memory to re-allocate.
nbytes New memory block size in bytes.
Returns:
Pointer to the allocated memory block.
The function changes the size of an already allocated memory block memblk to the new size nbytes bytes. The contents is unchanged to the minimum of old and new size; newly allocated memory is not initialized. If memblk is NULL the call to cpl_realloc() is equivalent to cpl_malloc(), and if nbytes is 0 the call is equivalent to cpl_free(). Unless memblk is NULL, it must have been returned by a previous call to cpl_malloc(), cpl_calloc(), or cpl_realloc().

Note:
  • The returned memory block returned on successfull allocation may not be the same as the one pointed to by memblk. Existing references pointing to locations within the original memory block might be invalidated!
  • If the memory subsytem has not been initialised before calling this function, the program execution is stopped printing a message to the error channel showing the current code position.
See also:
cpl_malloc(), cpl_calloc()

char* cpl_sprintf ( const char *  format,
  ... 
)

Create a string and fill it in an sprintf()-like manner.

Parameters:
format The format string
... Variable argument list for format
Returns:
The created string or NULL on error
Note:
The created string must be deallocated with cpl_free()
See also:
cpl_vsprintf()
The allocated memory is exactly what is needed to hold the string.

Errors:
CPL_ERROR_NULL_INPUT The format string is NULL.
CPL_ERROR_ILLEGAL_INPUT The format string has an invalid format.

Example of usage:

      int error;

      char * cp_cmd = cpl_sprintf("cp %s %s/%s", long_file, new_dir,
                                                    new_file);
      assert( cp_cmd != NULL);

      error = system(cp_cmd);

      assert(!error);

      cpl_free(cp_cmd);

char* cpl_strdup ( const char *  string  ) 

Duplicate a string.

Parameters:
string String to be duplicated.
Returns:
Newly allocated copy of the original string.
Duplicates the input string string. The newly allocated copy returned to the caller can be deallocated using cpl_free().

See also:
cpl_free()

char* cpl_vsprintf ( const char *  format,
va_list  arglist 
)

Create a string and fill it in an vsprintf()-like manner.

Parameters:
format The format string
arglist The argument list for the format
Returns:
The created string or NULL on error
Note:
The created string must be deallocated with cpl_free()
See also:
vsprintf()
The allocated memory is exactly what is needed to hold the string.

Errors:
CPL_ERROR_NULL_INPUT The format string is NULL.
CPL_ERROR_ILLEGAL_INPUT The format string has an invalid format.


Generated on Wed Mar 18 09:40:12 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7