Common Pipeline Library Reference Manual  5.3.1
Functions
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:
natomsNumber of atomic elements.
nbytesElement 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:
nbytesNumber 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:
memblkPointer to the memory to re-allocate.
nbytesNew 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:
formatThe 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:
stringString 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:
formatThe format string
arglistThe 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.