Common Pipeline Library Reference Manual 6.0
Functions

Library Initialization

Functions

void cpl_end (void)
 Stop the internal subsystems of CPL.
const char * cpl_get_description (unsigned self)
 Create a string of version numbers of CPL and its libraries.
void cpl_init (unsigned self)
 Initialise the CPL core library.

Detailed Description

The module provides the CPL library startup routine. The startup routine initialises CPL internal data structures. For this reason, any application using functions from the CPL libraries must call the startup routine prior to calling any other CPL function.

Synopsis:
   #include <cpl_init.h>

Function Documentation

void cpl_end ( void  )

Stop the internal subsystems of CPL.

Returns:
Nothing.
Note:
Currently, the behaviour of any CPL function becomes undefined after this function is called.

This function must be called after any other CPL function is called.

const char* cpl_get_description ( unsigned  self)

Create a string of version numbers of CPL and its libraries.

Parameters:
selfCPL_DESCRIPTION_DEFAULT
Returns:
A pointer to a constant character array
void cpl_init ( unsigned  self)

Initialise the CPL core library.

Parameters:
selfCPL_INIT_DEFAULT is the only supported value
Returns:
Nothing.
Note:
The function must be called once before any other CPL function.

This function sets up the library internal subsystems, which other CPL functions expect to be in a defined state. In particular, the CPL memory management and the CPL messaging systems are initialised by this function call.

One of the internal subsystems of CPL handles memory allocation. The default CPL memory mode is defined during the build procedure, this default can be changed during the call to cpl_init() via the environment variable CPL_MEMORY_MODE. The valid values are 0: Use the default system functions for memory handling 1: Exit if a memory-allocation fails, provide checking for memory leaks, limited reporting of memory allocation and limited protection on deallocation of invalid pointers. 2: Exit if a memory-allocation fails, provide checking for memory leaks, extended reporting of memory allocation and protection on deallocation of invalid pointers. Any other value (including NULL) will leave the default memory mode unchanged.

This function also reads the environment variable CPL_IO_MODE. If set to 1, CPL will use a new, somewhat experimental and optimized scheme for FITS I/O. Normally, when a FITS file is processed with a CPL call, the file is openened and closed during that call. However, repeated calls on FITS data with many extensions causes the FITS headers to be parsed many times, which can lead to a significant performance penalty. If instead CPL_IO_MODE is set to 1, CPL will use internal storage to keep the FITS files open between calls, and only close them when cpl_end() is called. Also, certain FITS operations such as completely replacing the contents of a FITS file that has already been read will cause the file to be closed and opened. This optimized I/O mode cannot be used if the CPL application accesses a FITS file without using CPL. En incomplete list of such access is: calls to rename(), unlink(), fopen() and access with other software started with for example system(). CPL_IO_MODE may be used in a multi- threaded environment to the extent that the underlying FITS library (CFITSIO) supports it.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_INCOMPATIBLE_INPUT if there is an inconsistency between the run- time and compile-time versions of a library that CPL depends on internally, e.g. CFITSIO. This error may occur with dynamic linking. If it does occur, the use of CPL may lead to unexpected behaviour.