FITS related basic routines

Typedefs
typedef enum _cpl_fits_mode_	cpl_fits_mode
	The CPL fits mode. It is a bit field.

Enumerations
enum	_cpl_fits_mode_ {   CPL_FITS_STOP_CACHING ,   CPL_FITS_START_CACHING ,   CPL_FITS_RESTART_CACHING ,   CPL_FITS_ONE }
	The values of the CPL fits mode. The values can be combined with bitwise or. More...

Functions
cpl_size	cpl_fits_count_extensions (const char *filename)
	Get the number of extensions contained in a FITS file.
cpl_size	cpl_fits_find_extension (const char *filename, const char *extname)
	Get the place of a given extension in a FITS file.
int	cpl_fits_get_extension_nb (const char *filename, const char *extname)
	Get the place of a given extension in a FITS file.
cpl_fits_mode	cpl_fits_get_mode (void)
	Get the FITS I/O mode.
int	cpl_fits_get_nb_extensions (const char *filename)
	Get the number of extensions contained in a FITS file.
cpl_error_code	cpl_fits_set_mode (cpl_fits_mode mode)
	Set the FITS I/O mode.

Detailed Description

This module provides functions to get basic information on FITS files

Synopsis:

#include "cpl_fits.h"

Typedef Documentation

cpl_fits_mode

typedef enum _cpl_fits_mode_ cpl_fits_mode

The CPL fits mode. It is a bit field.

Enumeration Type Documentation

_cpl_fits_mode_

enum _cpl_fits_mode_

The values of the CPL fits mode. The values can be combined with bitwise or.

Enumerator
CPL_FITS_STOP_CACHING	Stop the caching of open FITS files
CPL_FITS_START_CACHING	Start the caching of open FITS files
CPL_FITS_RESTART_CACHING	Restart the caching of open FITS files
CPL_FITS_ONE	Apply the mode change only to the current thread

Function Documentation

cpl_fits_count_extensions()

cpl_size cpl_fits_count_extensions

(

const char *

filename

)

Get the number of extensions contained in a FITS file.

Parameters

filename

The file name

Returns

The number of extensions or -1 in case of error

Note

For a valid fits file without extensions zero is returned

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if the input pointer is NULL
• CPL_ERROR_FILE_IO If the FITS file could not be opened
• CPL_ERROR_BAD_FILE_FORMAT if the input FITS file is otherwise invalid

References cpl_ensure, CPL_ERROR_BAD_FILE_FORMAT, CPL_ERROR_FILE_IO, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_fits_get_nb_extensions(), and cpl_frame_get_nextensions().

cpl_fits_find_extension()

cpl_size cpl_fits_find_extension	(	const char *	filename,
		const char *	extname
	)

Get the place of a given extension in a FITS file.

Parameters

filename	The file name
extname	The extension name

Returns

The extension number, 0 if not found or -1 on error

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if an input pointer is NULL
• CPL_ERROR_FILE_IO if the file is not FITS

References cpl_ensure, CPL_ERROR_FILE_IO, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_fits_get_extension_nb(), and cpl_multiframe_append_datagroup().

cpl_fits_get_extension_nb()

int cpl_fits_get_extension_nb	(	const char *	filename,
		const char *	extname
	)

Get the place of a given extension in a FITS file.

Parameters

filename	The file name
extname	The extension name

Returns

the extension place or -1 in case of error

See also

cpl_fits_find_extension

Deprecated:

Replace this call with cpl_fits_find_extension().

References cpl_fits_find_extension().

cpl_fits_get_mode()

cpl_fits_mode cpl_fits_get_mode

(

void

)

Get the FITS I/O mode.

Returns

One of: CPL_FITS_STOP_CACHING, CPL_FITS_START_CACHING

See also

cpl_fits_set_mode()

References CPL_FITS_START_CACHING, and CPL_FITS_STOP_CACHING.

cpl_fits_get_nb_extensions()

int cpl_fits_get_nb_extensions

(

const char *

filename

)

Get the number of extensions contained in a FITS file.

Parameters

filename

The file name

Returns

the number of extensions or -1 in case of error

See also

cpl_fits_count_extensions()

Deprecated:

Replace this call with cpl_fits_count_extensions().

References cpl_fits_count_extensions().

cpl_fits_set_mode()

cpl_error_code cpl_fits_set_mode

(

cpl_fits_mode

mode

)

Set the FITS I/O mode.

Parameters

mode	The FITS I/O mode: CPL_FITS_STOP_CACHING, CPL_FITS_START_CACHING, CPL_FITS_RESTART_CACHING

Returns

CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also

cpl_init() to control the FITS I/O mode when CPL is started

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 this function is called with CPL_FITS_START_CACHING, CPL will use internal storage to keep the FITS files open between calls and only close them when the FITS I/O mode is changed (or cpl_end() is called).

If a CPL function that creates a FITS file is called any previously opened handles to that file are closed. If a CPL function that appends to a FITS file is called any previously opened read-only handles to that file are closed. If a CPL function that reads from a FITS file is called any previously opened read/write-handle to that file is used for the read. Any additional concurrent reads causes the file to also be opened for reading. This means that there is also a performance gain when alternating between appending to and reading from the same file. This optimized I/O mode cannot be used if the CPL application accesses a FITS file without using CPL. An incomplete list of such access is: Calls to rename(), remove(), unlink(), fopen() and access via another process started with for example system() or popen().

The caching of opened FITS files may be used in a multi-threaded environment to the extent that the underlying FITS library (CFITSIO) supports it. One implication of this is that multiple threads may only call CPL FITS saving functions on the same file using proper synchronization such as the OpenMP 'ordered' construct. CPL makes no attempt to verify that a CPL based application performs thread parallel FITS I/O correctly.

The mode CPL_FITS_STOP_CACHING causes all cached filed to be closed. Beware that this can cause an I/O error for a file that has otherwise not been accessed for some time.

Since CPL_FITS_STOP_CACHING closes all cached FITS files, the caller must ensure that this does not interfere with the concurrent use of those same files in another thread.

The mode CPL_FITS_RESTART_CACHING has the same effect as a call with CPL_FITS_STOP_CACHING followed by a call with CPL_FITS_START_CACHING.

The modes CPL_FITS_RESTART_CACHING and CPL_FITS_ONE may be combined. This causes all files cached by the calling thread to be closed. The caching remains active (for all threads), so subsequently opened files will be cached.

CPL_FITS_RESTART_CACHING can be used after an external modification of a FITS file also cached by CPL, thus allowing the caching to work together with the above mentioned external access to the same FITS files.

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_ILLEGAL_INPUT if the mode is zero
• CPL_ERROR_UNSUPPORTED_MODE if the mode is not supported
• CPL_ERROR_INVALID_TYPE if mode is 1, e.g. due to a logical or (||) of the allowed options.
• CPL_ERROR_BAD_FILE_FORMAT if the I/O caused by CPL_FITS_STOP_CACHING failed

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_UNSUPPORTED_MODE, CPL_FITS_ONE, CPL_FITS_RESTART_CACHING, CPL_FITS_START_CACHING, and CPL_FITS_STOP_CACHING.

Referenced by cpl_end(), and cpl_init().