C Standard Library Extensions: FITS caching capabilities

C Standard Library Extensions 6.2.0

- Main Page
- Modules
- Classes
- Files

Functions
FITS caching capabilities

## Functions
void | qfits_cache_purge (void)
| Purge the qfits cache.
int | qfits_query (const char *filename, int what)
| Query a FITS file offset from the cache.

## Detailed Description

This modules implements a cache for FITS access routines. The first time a FITS file is seen by the library, all corresponding pointers are cached here. This speeds up multiple accesses to large files by magnitudes.

## Function Documentation

void qfits_cache_purge | ( | void |  | ) |

Purge the qfits cache.

Returns:
  void

This function is useful for programs running for a long period, to clean up the cache. Ideally in a daemon, it should be called by a timer at regular intervals. Notice that since the cache is fairly small, you should not need to care too much about this.

int qfits_query | ( | const char * | filename,
|  | int | what
| ) |  |

Query a FITS file offset from the cache.

Parameters:

  filename | Name of the file to examine.
  what | What should be queried (see below).

Returns:
  an integer offset, or -1 if an error occurred.

This function queries the cache for FITS offset information. If the requested file name has never been seen before, it is completely parsed to extract all offset informations, which are then stored in the cache. The next query will get the informations from the cache, avoiding a complete re-parsing of the file. This is especially useful for large FITS files with lots of extensions, because querying the extensions is an expensive operation.

This operation has side-effects: the cache is an automatically allocated structure in memory, that can only grow. Every request on a new FITS file will make it grow. The structure is pretty light-weight in memory, but nonetheless this is an issue for daemon-type programs which must run over long periods. The solution is to clean the cache using qfits_cache_purge() at regular intervals. This is left to the user of this library.

To request information about a FITS file, you must pass an integer built from the following symbols:

- `QFITS_QUERY_N_EXT`
- `QFITS_QUERY_HDR_START`
- `QFITS_QUERY_DAT_START`
- `QFITS_QUERY_HDR_SIZE`
- `QFITS_QUERY_DAT_SIZE`

Querying the number of extensions present in a file is done simply with:

next = qfits_query(filename, QFITS_QUERY_N_EXT);

Querying the offset to the i-th extension header is done with:

off = qfits_query(filename, QFITS_QUERY_HDR_START | i);

i.e. you must OR (|) the extension number with the `QFITS_QUERY_HDR_START` symbol. Requesting offsets to extension data is done in the same way:

off = qfits_query(filename, QFITS_QUERY_DAT_START | i);

Notice that extension 0 is the main header and main data part of the FITS file.

Referenced by qfits_get_datinfo(), qfits_get_hdrinfo(), and qfits_query_n_ext().