qfits.h File Reference


Data Structures

struct  qfits_col
 Column object. More...

struct  qfits_header
 FITS header object. More...

struct  qfits_table
 Table object. More...

struct  qfitsdumper
 qfits dumper control object. More...

struct  qfitsloader
 qfits loader control object. More...


Typedefs

typedef struct qfits_header  qfits_header
 FITS header object. More...

typedef unsigned char byte
 Alias for unsigned char. More...

typedef struct qfitsloader  qfitsloader
 qfits loader control object. More...

typedef struct qfitsdumper  qfitsdumper
 qfits dumper control object. More...

typedef enum _TFITS_DATA_TYPE_  tfits_type
 Column data type.

typedef struct qfits_col  qfits_col
 Column object. More...

typedef struct qfits_table  qfits_table
 Table object. More...


Enumerations

enum  _TFITS_DATA_TYPE_ {
  TFITS_ASCII_TYPE_A, TFITS_ASCII_TYPE_D, TFITS_ASCII_TYPE_E, TFITS_ASCII_TYPE_F,
  TFITS_ASCII_TYPE_I, TFITS_BIN_TYPE_A, TFITS_BIN_TYPE_B, TFITS_BIN_TYPE_C,
  TFITS_BIN_TYPE_D, TFITS_BIN_TYPE_E, TFITS_BIN_TYPE_I, TFITS_BIN_TYPE_J,
  TFITS_BIN_TYPE_L, TFITS_BIN_TYPE_M, TFITS_BIN_TYPE_P, TFITS_BIN_TYPE_X,
  TFITS_BIN_TYPE_UNKNOWN
}
 Column data type. More...


Functions

char* qfits_version (void)
void qfits_cache_purge (void)
 Purge the qfits cache. More...

char* qfits_expand_keyword (char *keyword)
 Expand a keyword from shortFITS to HIERARCH notation. More...

qfits_headerqfits_header_new (void)
 FITS header constructor. More...

qfits_headerqfits_header_default (void)
 FITS header default constructor. More...

void qfits_header_add (qfits_header *hdr, char *key, char *val, char *com, char *lin)
 Add a new card to a FITS header. More...

void qfits_header_add_after (qfits_header *hdr, char *after, char *key, char *val, char *com, char *lin)
 add a new card to a FITS header. More...

void qfits_header_append (qfits_header *hdr, char *key, char *val, char *com, char *lin)
 Append a new card to a FITS header. More...

void qfits_header_del (qfits_header *hdr, char *key)
 Delete a card in a FITS header. More...

void qfits_header_mod (qfits_header *hdr, char *key, char *val, char *com)
 Modifies a FITS card. More...

int qfits_header_sort (qfits_header **hdr)
 Sort a FITS header. More...

qfits_headerqfits_header_copy (qfits_header *src)
 Copy a FITS header. More...

void qfits_header_touchall (qfits_header *hdr)
 Touch all cards in a FITS header. More...

void qfits_header_consoledump (qfits_header *hdr)
 Dump a FITS header to stdout. More...

void qfits_header_destroy (qfits_header *hdr)
 qfits_header destructor. More...

char* qfits_header_getstr (qfits_header *hdr, char *key)
 Return the value associated to a key, as a string. More...

char* qfits_header_findmatch (qfits_header *hdr, char *key)
 Find a matching key in a header. More...

int qfits_header_getitem (qfits_header *hdr, int idx, char *key, char *val, char *com, char *lin)
 Return the i-th key/val/com/line tuple in a header. More...

char* qfits_header_getline (qfits_header *hdr, char *key)
 Return the FITS line associated to a key, as a string. More...

char* qfits_header_getcom (qfits_header *hdr, char *key)
 Return the comment associated to a key, as a string. More...

int qfits_header_getint (qfits_header *hdr, char *key, int errval)
 Return the value associated to a key, as an int. More...

double qfits_header_getdouble (qfits_header *hdr, char *key, double errval)
 Return the value associated to a key, as a double. More...

int qfits_header_getboolean (qfits_header *hdr, char *key, int errval)
 Return the value associated to a key, as a boolean (int). More...

void keytuple2str (char *line, char *key, char *val, char *com)
 Write out a key tuple to a string on 80 chars. More...

int qfits_header_dump (qfits_header *hdr, FILE *out)
 Dump a FITS header to an opened file. More...

int qfits_header_dump_hdr (qfits_header *hdr, FILE *out)
 Dump a FITS header to an opened file (one card per line). More...

char* qfits_header_to_memblock (qfits_header *fh, int *hsize)
 Dump a fits header into a memory block. More...

char* qfits_datamd5 (char *filename)
 Compute the MD5 hash of data zones in a FITS file. More...

char* qfits_getkey (char *line)
 Find the keyword in a key card (80 chars). More...

char* qfits_getvalue (char *line)
 Find the value in a key card (80 chars). More...

char* qfits_getcomment (char *line)
 Find the comment in a key card (80 chars). More...

qfits_headerqfits_header_read (char *filename)
 Read a FITS header from a file to an internal structure. More...

qfits_headerqfits_header_read_hdr (char *filename)
 Read a FITS header from a 'hdr' file. More...

qfits_headerqfits_header_readext (char *filename, int xtnum)
 Read an extension header from a FITS file. More...

void qfits_zeropad (char *filename)
 Pad an existing file with zeros to a multiple of 2880. More...

int is_fits_file (char *filename)
 Identify if a file is a FITS file. More...

char* qfits_get_dir_name (char *filename)
 Find the directory name in the given string. More...

char* qfits_get_base_name (const char *filename)
 Find out the base name of a file (i.e. without prefix path). More...

char* qfits_get_root_name (char *filename)
 Find out the root part of a basename (name without extension). More...

char* qfits_get_ext_name (char *filename)
 Find out the extension of a file name. More...

char* qfits_get_login_name (void)
 Returns the user login name. More...

int _qfits_isnanf (float f)
int _qfits_isinff (float f)
int _qfits_isnand (double d)
int _qfits_isinfd (double d)
FILE* qfits_paf_print_header (char *filename, char *paf_id, char *paf_desc, char *login_name, char *datetime)
 Open a new PAF file, output a default header. More...

char* qfits_paf_query (char *filename, char *key)
 Query a PAF file for a value. More...

int qfits_is_paf_file (char *filename)
 returns 1 if file is in PAF format, 0 else. More...

int qfitsloader_init (qfitsloader *ql)
 Initialize a qfitsloader control object. More...

int qfits_loadpix (qfitsloader *ql)
 Load a pixel buffer for one image. More...

float* qfits_pixin_float (byte *, int, int, double, double)
 Load a pixel buffer as floats. More...

int* qfits_pixin_int (byte *, int, int, double, double)
 Load a pixel buffer as ints. More...

double* qfits_pixin_double (byte *, int, int, double, double)
 Load a pixel buffer as doubles. More...

int qfits_pixdump (qfitsdumper *qd)
 Dump a pixel buffer to an output FITS file in append mode. More...

byteqfits_pixdump_float (float *buf, int npix, int ptype)
 Convert a float pixel buffer to a byte buffer. More...

byteqfits_pixdump_int (int *buf, int npix, int ptype)
 Convert an int pixel buffer to a byte buffer. More...

byteqfits_pixdump_double (double *buf, int npix, int ptype)
 Convert a double pixel buffer to a byte buffer. More...

int qfits_err_statget (void)
 Get the current status of error display. More...

int qfits_err_statset (int sta)
 Set the current status of error display. More...

int qfits_err_register (void(*dispfn)(char *))
 Register a function to display error/warning messages. More...

char* qfits_query_hdr (char *filename, char *keyword)
 Retrieve the value of a key in a FITS header. More...

char* qfits_query_ext (char *filename, char *keyword, int xtnum)
 Retrieve the value of a keyin a FITS extension header. More...

int qfits_query_n_ext (char *filename)
 Counts the number of extensions in a FITS file. More...

int qfits_query_nplanes (char *filename, int extnum)
 Counts the number of planes in a FITS extension. More...

char* qfits_pretty_string (char *s)
 Clean out a FITS string value. More...

int qfits_is_boolean (char *s)
 Identify if a FITS value is boolean. More...

int qfits_is_int (char *s)
 Identify if a FITS value is an int. More...

int qfits_is_float (char *s)
 Identify if a FITS value is float. More...

int qfits_is_complex (char *s)
 Identify if a FITS value is complex. More...

int qfits_is_string (char *s)
 Identify if a FITS value is string. More...

int qfits_get_type (char *s)
 Identify the type of a FITS value given as a string. More...

int qfits_get_hdrinfo (char *filename, int xtnum, int *seg_start, int *seg_size)
 Retrieve offset to start and size of a header in a FITS file. More...

int qfits_get_datinfo (char *filename, int xtnum, int *seg_start, int *seg_size)
 Retrieve offset to start and size of a data section in a file. More...

char* qfits_query_card (char *filename, char *keyword)
 Query a card in a FITS (main) header by a given key. More...

int qfits_replace_card (char *filename, char *keyword, char *substitute)
 Replace a card in a FITS (main) header by a given card. More...

long qfits_date_now (void)
 Returns the current date as a long (CCYYMMDD). More...

long qfits_time_now (void)
 Returns the current time as a long (HHMMSSCC). More...

char* qfits_get_date_iso8601 (void)
 Returns the current date as a static string. More...

char* qfits_get_datetime_iso8601 (void)
 Returns the current date and time as a static string. More...

int qfits_is_table (char *filename, int xtnum)
 Identify a file as containing a FITS table in extension. More...

qfits_headerqfits_table_prim_header_default (void)
 Generate a default primary header to store tables. More...

qfits_headerqfits_table_ext_header_default (qfits_table *)
 Generate a default extension header to store tables. More...

qfits_tableqfits_table_new (char *filename, int table_type, int table_width, int nb_cols, int nb_raws)
 Table object constructor. More...

int qfits_col_fill (qfits_col *qc, int atom_nb, int atom_dec_nb, int atom_size, tfits_type atom_type, char *label, char *unit, char *nullval, char *disp, int zero_present, float zero, int scale_present, float scale, int offset_beg)
 Fill a column object with some provided informations. More...

qfits_tableqfits_table_open (char *filename, int xtnum)
 Read a FITS extension. More...

void qfits_table_close (qfits_table *t)
 Free a FITS table and associated pointers. More...

unsigned char* qfits_query_column (qfits_table *th, int colnum, int *selection)
 Extract data from a column in a FITS table. More...

unsigned char* qfits_query_column_seq (qfits_table *th, int colnum, int start_ind, int nb_rows)
 Extract consequtive values from a column in a FITS table. More...

int qfits_compute_table_width (qfits_table *th)
 Compute the table width in bytes from the columns infos. More...

void* qfits_query_column_data (qfits_table *th, int colnum, int *selection, void *null_value)
 Extract binary data from a column in a FITS table. More...

void* qfits_query_column_seq_data (qfits_table *th, int colnum, int start_ind, int nb_rows, void *null_value)
 Extract binary data from a column in a FITS table. More...

int* qfits_query_column_nulls (qfits_table *th, int colnum, int *selection, int *nb_vals, int *nb_nulls)
 Detect NULL values in a column. More...

int qfits_save_table_hdrdump (void **array, qfits_table *table, qfits_header *fh)
 Save a table to a FITS file with a given FITS header. More...

int qfits_table_append_xtension (FILE *outfile, qfits_table *t, void **data)
 Appends a std extension header + data to a FITS table file. More...

int qfits_table_append_xtension_hdr (FILE *outfile, qfits_table *t, void **data, qfits_header *hdr)
 Appends a specified extension header + data to a FITS table file. More...

char* qfits_table_field_to_string (qfits_table *table, int col_id, int row_id, int use_zero_scale)
 given a col and a row, find out the string to write for display. More...


Typedef Documentation

typedef unsigned char byte
 

Alias for unsigned char.

A 'byte' is just an alias for an unsigned char. It is only defined for readability.

typedef struct qfits_col qfits_col
 

Column object.

This structure contains all information needed to read a column in a table. These informations come from the header. The qfits_table object contains a list of qfits_col objects.

This structure has to be created from scratch and filled if one want to generate a FITS table.

typedef struct qfits_header qfits_header
 

FITS header object.

This structure represents a FITS header in memory. It is actually no more than a thin layer on top of the keytuple object. No field in this structure should be directly modifiable by the user, only through accessor functions.

typedef struct qfits_table qfits_table
 

Table object.

This structure contains all information needed to read a FITS table. These information come from the header. The object is created by qfits_open().

To read a FITS table, here is a code example:

  int main(int argc, char* argv[])
  {
    qfits_table     *   table ;
    int                 n_ext ;
    int                 i ;

    // Query the number of extensions
    n_ext = qfits_query_n_ext(argv[1]) ;
    
    // For each extension
    for (i=0 ; i<n_ext ; i++) {
        // Read all the infos about the current table 
        table = qfits_table_open(argv[1], i+1) ;
        // Display the current table 
        dump_extension(table, stdout, '|', 1, 1) ;
    }
    return ;
  }

typedef struct qfitsdumper qfitsdumper
 

qfits dumper control object.

This structure offers various control parameters to dump a pixel buffer to a FITS file. The buffer will be dumped as requested to the requested file in append mode. Of course, the requested file must be writeable for the operation to succeed.

The following example demonstrates how to save a linear ramp sized 100x100 to a FITS file with BITPIX=16. Notice that this code only dumps the pixel buffer, no header information is provided in this case.

    int   i, j ;
    int * ibuf ;
    qfitsdumper qd ;

    // Fill a buffer with 100x100 int pixels
    ibuf = malloc(100 * 100 * sizeof(int));
    for (j=0 ; j<100 ; j++) {
        for (i=0 ; i<100 ; i++) {
            ibuf[i+j*100] = i+j ;
        }
    }

    qd.filename  = "out.fits" ;     // Output file name
    qd.npix      = 100 * 100 ;      // Number of pixels
    qd.ptype     = PTYPE_INT ;      // Input buffer type
    qd.ibuf      = ibuf ;           // Set buffer pointer
    qd.out_ptype = BPP_16_SIGNED ;  // Save with BITPIX=16

    // Dump buffer to file (error checking omitted for clarity)
    qfits_pixdump(&qd);

    free(ibuf);

If the provided output file name is "STDOUT" (all capitals), the function will dump the pixels to the stdout steam (usually the console, could have been re-directed).

typedef struct qfitsloader qfitsloader
 

qfits loader control object.

This structure serves two purposes: input and output for the qfits pixel loading facility. To request pixels from a FITS file, you need to allocate (statically or dynamically) such a structure and fill up the input fields (filename, xtension number, etc.) to specify the pixels you want from the file.

Before performing the actual load, you must pass the initialized structure to qfitsloader_init() which will check whether the operation is feasible or not (check its returned value).

If the operation was deemed feasible, you can proceed to load the pixels, passing the same structure to qfits_loadpix() which will fill up the output fields of the struct. Notice that a pixel buffer will have been allocated (through malloc or mmap) and placed into the structure. You need to call free() on this pointer when you are done with it, typically in the image or cube destructor.

The qfitsloader_init() function is also useful to probe a FITS file for useful informations, like getting the size of images in the file, the pixel depth, or data offset.

Example of a code that prints out various informations about a plane to load, without actually loading it:

int main(int argc, char * argv[])
{
    qfitsloader ql ;

    ql.filename = argv[1] ;
    ql.xtnum    = 0 ;
    ql.pnum     = 0 ;

    if (qfitsloader_init(&ql)!=0) {
        printf("cannot read info about %s\n", argv[1]);
        return -1 ;
    }

    printf( "file         : %s\n"
            "xtnum        : %d\n"
            "pnum         : %d\n"
            "# xtensions  : %d\n"
            "size X       : %d\n"
            "size Y       : %d\n"
            "planes       : %d\n"
            "bitpix       : %d\n"
            "datastart    : %d\n"
            "datasize     : %d\n"
            "bscale       : %g\n"
            "bzero        : %g\n",
            ql.filename,
            ql.xtnum,
            ql.pnum,
            ql.exts,
            ql.lx,
            ql.ly,
            ql.np,
            ql.bitpix,
            ql.seg_start,
            ql.seg_size,
            ql.bscale,
            ql.bzero);
    return 0 ;
}

typedef enum _TFITS_DATA_TYPE_ tfits_type
 

Column data type.


Enumeration Type Documentation

enum _TFITS_DATA_TYPE_
 

Column data type.

Enumeration values:
TFITS_ASCII_TYPE_A  
TFITS_ASCII_TYPE_D  
TFITS_ASCII_TYPE_E  
TFITS_ASCII_TYPE_F  
TFITS_ASCII_TYPE_I  
TFITS_BIN_TYPE_A  
TFITS_BIN_TYPE_B  
TFITS_BIN_TYPE_C  
TFITS_BIN_TYPE_D  
TFITS_BIN_TYPE_E  
TFITS_BIN_TYPE_I  
TFITS_BIN_TYPE_J  
TFITS_BIN_TYPE_L  
TFITS_BIN_TYPE_M  
TFITS_BIN_TYPE_P  
TFITS_BIN_TYPE_X  
TFITS_BIN_TYPE_UNKNOWN  


Function Documentation

int _qfits_isinfd ( double d )
 

Test a double variable for Inf value. Do not call directly, call qfits_isinf().

int _qfits_isinff ( float f )
 

Test a float variable for Inf value. Do not call directly, call qfits_isinf().

int _qfits_isnand ( double d )
 

Test a double variable for NaN value. Do not call directly, call qfits_isnan().

int _qfits_isnanf ( float f )
 

Test a float variable for NaN value. Do not call directly, call qfits_isnan().

int is_fits_file ( char * filename )
 

Identify if a file is a FITS file.

Parameters:
filename   name of the file to check
Returns:
int 0, 1, or -1

Returns 1 if the file name looks like a valid FITS file. Returns 0 else. If the file does not exist, returns -1.

void keytuple2str ( char * line,
char * key,
char * val,
char * com )
 

Write out a key tuple to a string on 80 chars.

Parameters:
line   Allocated output character buffer.
key   Key to write.
val   Value to write.
com   Comment to write.
Returns:
void

Write out a key, value and comment into an allocated character buffer. The buffer must be at least 80 chars to receive the information. Formatting is done according to FITS standard.

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_col_fill ( qfits_col * qc,
int atom_nb,
int atom_dec_nb,
int atom_size,
tfits_type atom_type,
char * label,
char * unit,
char * nullval,
char * disp,
int zero_present,
float zero,
int scale_present,
float scale,
int offset_beg )
 

Fill a column object with some provided informations.

Parameters:
qc   Pointer to the column that has to be filled
unit   Unit of the data
label   Label of the column
disp   Way to display the data
nullval   Null value
atom_nb   Number of atoms per field. According to the type, an atom is a double, an int, a char, ...
atom_dec_nb   Number of decimals as specified in TFORM
atom_size   Size in bytes of the field for ASCII tables, and of an atom for BIN tables. ASCII tables only contain 1 atom per field (except for A type where you can of course have more than one char per field)
atom_type   Type of data (11 types for BIN, 5 for ASCII)
zero_present   Flag to use or not zero
zero   Zero value
scale_present   Flag to use or not scale
scale   Scale value
offset_beg   Gives the position of the column
Returns:
-1 in error case, 0 otherwise

int qfits_compute_table_width ( qfits_table * th )
 

Compute the table width in bytes from the columns infos.

Parameters:
th   Allocated qfits_table
Returns:
the width (-1 in error case)

char * qfits_datamd5 ( char * filename )
 

Compute the MD5 hash of data zones in a FITS file.

Parameters:
filename   Name of the FITS file to examine.
Returns:
1 statically allocated character string, or NULL.

This function expects the name of a FITS file. It will compute the MD5 hash on all data blocks in the main data section and possibly extensions (including zero-padding blocks if necessary) and return it as a string suitable for inclusion into a FITS keyword.

The returned string is statically allocated inside this function, so do not free it or modify it. This function returns NULL in case of error.

long qfits_date_now ( void )
 

Returns the current date as a long (CCYYMMDD).

Returns:
The current date as a long number.

Returns the current date as a long value (CCYYMMDD). Since most system clocks do not return a century, this function assumes that all years 80 and above are in the 20th century, and all years 00 to 79 are in the 21st century. For best results, consume before 1 Jan 2080.

Example: 19 Oct 2000 is returned as 20001019

int qfits_err_register ( void(* dispfn)(char *) )
 

Register a function to display error/warning messages.

Parameters:
dispfn   Display function (see doc below).
Returns:
int 0 if function was registered, -1 if not.

This function registers a display function into the error-handling module. Display functions have the following prototype:

  void display_function(char * msg);

They are simple functions that expect a ready-made error message and return void. They can do whatever they want with the message (log it to a file, send it to a GUI, to the syslog, ...). The message is built using a printf-like statement in qfits_error and qfits_warning, then passed to all registered display functions.

A maximum of QFITS_ERR_MAXERRDISP can be registered (see source code). If the limit has been reached, this function will signal it by returning -1.

int qfits_err_statget ( void )
 

Get the current status of error display.

Returns:
int 1 if error display is active, 0 if not.

This function returns the current error display status. If it returns 1, it means that all calls to qfits_error/qfits_warning will display messages using the registered functions, otherwise they do nothing.

int qfits_err_statset ( int sta )
 

Set the current status of error display.

Parameters:
sta   New status to be set.
Returns:
int giving the previous display status.

This function sets the current error display status to the required value, and returns the previous value. It is useful to store the previous value, in view of restoring it afterwards, e.g. to make a function silent on all its errors. Example:

\begin{verbatim} int prev_stat = qfits_err_statset(0) ; function_call() ; qfits_err_statset(prev_stat); \end{verbatim}

char * qfits_expand_keyword ( char * keyword )
 

Expand a keyword from shortFITS to HIERARCH notation.

Parameters:
keyword   Keyword to expand.
Returns:
1 pointer to statically allocated string.

This function expands a given keyword from shortFITS to HIERARCH notation, bringing it to uppercase at the same time.

Examples:

  det.dit          expands to     HIERARCH ESO DET DIT
  ins.filt1.id     expands to     HIERARCH ESO INS FILT1 ID
  

If the input keyword is a regular FITS keyword (i.e. it contains not dots '.') the result is identical to the input.

char * qfits_get_base_name ( const char * filename )
 

Find out the base name of a file (i.e. without prefix path).

Parameters:
filename   Full path name to scan.
Returns:
Pointer to char within the input string.

Provide a full path name and you get in return a pointer to a statically allocated string containing the name of the file only, without prefixing directory names. If the input string does not contain a slash (i.e. it is not a full path), the returned string is a copy of the input string.

This function does not check for the existence of the path or the file.

Examples:

    qfits_get_base_name("/cdrom/data/image.fits") returns "image.fits"
    qfits_get_base_name("filename.fits") returns "filename.fits"
  

char * qfits_get_date_iso8601 ( void )
 

Returns the current date as a static string.

Returns:
Pointer to statically allocated string.

Build and return a string containing the date of today in ISO8601 format. The returned pointer points to a statically allocated string in the function, so no need to free it.

char * qfits_get_datetime_iso8601 ( void )
 

Returns the current date and time as a static string.

Returns:
Pointer to statically allocated string

Build and return a string containing the date of today and the current time in ISO8601 format. The returned pointer points to a statically allocated string in the function, so no need to free it.

int qfits_get_datinfo ( char * filename,
int xtnum,
int * seg_start,
int * seg_size )
 

Retrieve offset to start and size of a data section in a file.

Parameters:
filename   Name of the file to examine.
xtnum   Extension number (0 for main).
seg_start   Segment start in bytes (output).
seg_size   Segment size in bytes (output).
Returns:
int 0 if Ok, -1 otherwise.

This function retrieves the two most important informations about a data section in a FITS file: the offset to its beginning, and the size of the section in bytes. Both values are returned in the passed pointers to ints. It is Ok to pass NULL for any pointer if you do not want to retrieve the associated value.

You must provide an extension number for the header, 0 meaning the main header in the file.

char * qfits_get_dir_name ( char * filename )
 

Find the directory name in the given string.

Parameters:
filename   Full path name to scan.
Returns:
Pointer to statically allocated string.

Provide a full path name and you get in return a pointer to a statically allocated string containing the name of the directory only, without trailing slash. If the input string does not contain a slash (i.e. it is not a full path), the returned string is '.', corresponding to the current working directory. Since the returned string is statically allocated, do not try to free it or modify it.

This function does not check for the existence of the path or the file.

Examples:

    get_dir_name("/cdrom/data/image.fits") returns "/cdrom/data"
    get_dir_name("filename.fits") returns "."
  

char * qfits_get_ext_name ( char * filename )
 

Find out the extension of a file name.

Parameters:
filename   File name without path prefix.
Returns:
Pointer to char within the input string.

Find out the extension of a given file name. Notice that the input character string must not contain a path prefix (typically, you feed in the output of qfits_get_base_name).

Works with all kinds of extensions: returns the part of the string after the last dot. If no dot is found in the input string, NULL is returned.

Examples:

    get_ext_name("filename.fits") returns "fits"
    get_ext_name("hello.c") returns "c"
    get_ext_name("readme") returns NULL
  

int qfits_get_hdrinfo ( char * filename,
int xtnum,
int * seg_start,
int * seg_size )
 

Retrieve offset to start and size of a header in a FITS file.

Parameters:
filename   Name of the file to examine
xtnum   Extension number (0 for main)
seg_start   Segment start in bytes (output)
seg_size   Segment size in bytes (output)
Returns:
int 0 if Ok, -1 otherwise.

This function retrieves the two most important informations about a header in a FITS file: the offset to its beginning, and the size of the header in bytes. Both values are returned in the passed pointers to ints. It is Ok to pass NULL for any pointer if you do not want to retrieve the associated value.

You must provide an extension number for the header, 0 meaning the main header in the file.

char * qfits_get_login_name ( void )
 

Returns the user login name.

Returns:
Pointer to statically allocated character string.

Finds out what the login name of the current user is. The result is placed in a static character string inside this module and a pointer to the first character in this string is returned. Do not modify or free the returned string!

If the user name cannot be determined, the returned pointer will point to a string which first character is a null character.

char * qfits_get_root_name ( char * filename )
 

Find out the root part of a basename (name without extension).

Parameters:
filename   File name to scan.
Returns:
Pointer to statically allocated string.

Find out the root part of a file name, i.e. the file name without extension. Since in Unix a file name can have several dots, only a number of extensions are supported. This includes:

  • .fits and .FITS
  • .tfits and .TFITS
  • .paf and .PAF
  • .ascii and .ASCII
  • .dat and .DAT
This function does not check for the existence of the path or the file.

Examples:

    get_root_name("/cdrom/filename.fits") returns "/cdrom/filename"
    get_root_name("filename.paf") returns "filename"
    get_root_name("filename") returns "filename"
    get_root_name("filename.ext") returns "filename.ext"
  

Since the returned string is statically allocated in this module, do not try to free it or modify its contents.

int qfits_get_type ( char * s )
 

Identify the type of a FITS value given as a string.

Parameters:
s   FITS value as a string
Returns:
integer naming the FITS type

Returns the following value:

  • QFITS_UNKNOWN (0) for an unknown type.
  • QFITS_BOOLEAN (1) for a boolean type.
  • QFITS_INT (2) for an integer type.
  • QFITS_FLOAT (3) for a floating-point type.
  • QFITS_COMPLEX (4) for a complex number.
  • QFITS_STRING (5) for a FITS string.

char * qfits_getcomment ( char * line )
 

Find the comment in a key card (80 chars).

Parameters:
line   allocated 80-char line from a FITS header
Returns:
statically allocated char *

Find out the part of a FITS line corresponding to the comment. Returns NULL in case of error, or if no comment can be found. The returned pointer is statically allocated in this function, so do not modify or try to free it.

char * qfits_getkey ( char * line )
 

Find the keyword in a key card (80 chars).

Parameters:
line   allocated 80-char line from a FITS header
Returns:
statically allocated char *

Find out the part of a FITS line corresponding to the keyword. Returns NULL in case of error. The returned pointer is statically allocated in this function, so do not modify or try to free it.

char * qfits_getvalue ( char * line )
 

Find the value in a key card (80 chars).

Parameters:
line   allocated 80-char line from a FITS header
Returns:
statically allocated char *

Find out the part of a FITS line corresponding to the value. Returns NULL in case of error, or if no value can be found. The returned pointer is statically allocated in this function, so do not modify or try to free it.

void qfits_header_add ( qfits_header * hdr,
char * key,
char * val,
char * com,
char * lin )
 

Add a new card to a FITS header.

Parameters:
hdr   qfits_header object to modify
key   FITS key
val   FITS value
com   FITS comment
lin   FITS original line if exists
Returns:
void

This function adds a new card into a header, at the one-before-last position, i.e. the entry just before the END entry if it is there. The key must always be a non-NULL string, all other input parameters are allowed to get NULL values.

void qfits_header_add_after ( qfits_header * hdr,
char * after,
char * key,
char * val,
char * com,
char * lin )
 

add a new card to a FITS header.

Parameters:
hdr   qfits_header object to modify
after   Key to specify insertion place
key   FITS key
val   FITS value
com   FITS comment
lin   FITS original line if exists
Returns:
void

Adds a new card to a FITS header, after the specified key. Nothing happens if the specified key is not found in the header. All fields can be NULL, except after and key.

void qfits_header_append ( qfits_header * hdr,
char * key,
char * val,
char * com,
char * lin )
 

Append a new card to a FITS header.

Parameters:
hdr   qfits_header object to modify
key   FITS key
val   FITS value
com   FITS comment
lin   FITS original line if exists
Returns:
void

Adds a new card in a FITS header as the last one. All fields can be NULL except key.

void qfits_header_consoledump ( qfits_header * hdr )
 

Dump a FITS header to stdout.

Parameters:
hdr   qfits_header to dump
Returns:
void

Dump a FITS header to stdout. Mostly for debugging purposes.

qfits_header * qfits_header_copy ( qfits_header * src )
 

Copy a FITS header.

Parameters:
src   Header to replicate
Returns:
Pointer to newly allocated qfits_header object.

Makes a strict copy of all information contained in the source header. The returned header must be freed using qfits_header_destroy.

qfits_header * qfits_header_default ( void )
 

FITS header default constructor.

Returns:
1 newly allocated qfits_header object.

This is a secondary constructor for a qfits_header object. It returns an allocated linked-list handler containing two cards: the first one (SIMPLE=T) and the last one (END).

void qfits_header_del ( qfits_header * hdr,
char * key )
 

Delete a card in a FITS header.

Parameters:
hdr   qfits_header to modify
key   specifies which card to remove
Returns:
void

Removes a card from a FITS header. The first found card that matches the key is removed.

void qfits_header_destroy ( qfits_header * hdr )
 

qfits_header destructor.

Parameters:
hdr   qfits_header to deallocate
Returns:
void

Frees all memory associated to a given qfits_header object.

int qfits_header_dump ( qfits_header * hdr,
FILE * out )
 

Dump a FITS header to an opened file.

Parameters:
hdr   FITS header to dump
out   Opened file pointer
Returns:
int 0 if Ok, -1 otherwise

Dumps a FITS header to an opened file pointer.

int qfits_header_dump_hdr ( qfits_header * hdr,
FILE * out )
 

Dump a FITS header to an opened file (one card per line).

Parameters:
hdr   FITS header to dump
out   Opened file pointer
Returns:
int 0 if Ok, -1 otherwise
See also:
qfits_header_dump() Dumps a FITS header to an opened file pointer. This function is meant to create hdr files.

char * qfits_header_findmatch ( qfits_header * hdr,
char * key )
 

Find a matching key in a header.

Parameters:
hdr   qfits_header to parse
key   Key prefix to match
Returns:
pointer to statically allocated string.

This function finds the first keyword in the given header for which the given 'key' is a prefix, and returns the full name of the matching key (NOT ITS VALUE). This is useful to locate any keyword starting with a given prefix. Careful with HIERARCH keywords, the shortFITS notation is not likely to be accepted here.

Examples:

  s = qfits_header_findmatch(hdr, "SIMP") returns "SIMPLE"
  s = qfits_header_findmatch(hdr, "HIERARCH ESO DET") returns
  the first detector keyword among the HIERACH keys.
  

int qfits_header_getboolean ( qfits_header * hdr,
char * key,
int errval )
 

Return the value associated to a key, as a boolean (int).

Parameters:
hdr   qfits_header to parse
key   key to find
errval   default value to return if nothing is found
Returns:
int

Finds the value associated to the given key and return it as a boolean. Returns errval if no matching key is found or no value is attached. A boolean is here understood as an int taking the value 0 or 1. errval can be set to any other integer value to reflect that nothing was found.

errval is returned if no matching key is found or no value is attached.

A true value is any character string beginning with a 'y' (yes), a 't' (true) or the digit '1'. A false value is any character string beginning with a 'n' (no), a 'f' (false) or the digit '0'.

char * qfits_header_getcom ( qfits_header * hdr,
char * key )
 

Return the comment associated to a key, as a string.

Parameters:
hdr   qfits_header to parse
key   key to find
Returns:
pointer to statically allocated string @doc

Finds the comment associated to the given key and return it as a string. The returned pointer is statically allocated, so do not modify its contents or try to free it.

Returns NULL if no matching key is found or no comment is attached.

double qfits_header_getdouble ( qfits_header * hdr,
char * key,
double errval )
 

Return the value associated to a key, as a double.

Parameters:
hdr   qfits_header to parse
key   key to find
errval   default value to return if nothing is found
Returns:
double

Finds the value associated to the given key and return it as a double. Returns errval if no matching key is found or no value is attached.

int qfits_header_getint ( qfits_header * hdr,
char * key,
int errval )
 

Return the value associated to a key, as an int.

Parameters:
hdr   qfits_header to parse
key   key to find
errval   default value to return if nothing is found
Returns:
int

Finds the value associated to the given key and return it as an int. Returns errval if no matching key is found or no value is attached.

int qfits_header_getitem ( qfits_header * hdr,
int idx,
char * key,
char * val,
char * com,
char * lin )
 

Return the i-th key/val/com/line tuple in a header.

Parameters:
hdr   Header to consider
idx   Index of the requested card
key   Output key
val   Output value
com   Output comment
lin   Output initial line
Returns:
int 0 if Ok, -1 if error occurred.

This function is useful to browse a FITS header object card by card. By iterating on the number of cards (available in the 'n' field of the qfits_header struct), you can retrieve the FITS lines and their components one by one. Indexes run from 0 to n-1. You can pass NULL values for key, val, com or lin if you are not interested in a given field.

  int i ;
  char key[FITS_LINESZ+1] ;
  char val[FITS_LINESZ+1] ;
  char com[FITS_LINESZ+1] ;
  char lin[FITS_LINESZ+1] ;

  for (i=0 ; i<hdr->n ; i++) {
    qfits_header_getitem(hdr, i, key, val, com, lin);
    printf("card[%d] key[%s] val[%s] com[%s]\n", i, key, val, com);
  }

This function has primarily been written to interface a qfits_header object to other languages (C++/Python). If you are working within a C program, you should use the other header manipulation routines available in this module.

char * qfits_header_getline ( qfits_header * hdr,
char * key )
 

Return the FITS line associated to a key, as a string.

Parameters:
hdr   qfits_header to parse
key   key to find
Returns:
pointer to statically allocated string

Finds the FITS line associated to the given key and return it as a string. The returned pointer is statically allocated, so do not modify its contents or try to free it.

Returns NULL if no matching key is found or no line is attached.

char * qfits_header_getstr ( qfits_header * hdr,
char * key )
 

Return the value associated to a key, as a string.

Parameters:
hdr   qfits_header to parse
key   key to find
Returns:
pointer to statically allocated string

Finds the value associated to the given key and return it as a string. The returned pointer is statically allocated, so do not modify its contents or try to free it.

Returns NULL if no matching key is found or no value is attached.

void qfits_header_mod ( qfits_header * hdr,
char * key,
char * val,
char * com )
 

Modifies a FITS card.

Parameters:
hdr   qfits_header to modify
key   FITS key
val   FITS value
com   FITS comment
Returns:
void

Finds the first card in the header matching 'key', and replaces its value and comment fields by the provided values. The initial FITS line is set to NULL in the card.

qfits_header * qfits_header_new ( void )
 

FITS header constructor.

Returns:
1 newly allocated (empty) FITS header object.

This is the main constructor for a qfits_header object. It returns an allocated linked-list handler with an empty card list.

qfits_header * qfits_header_read ( char * filename )
 

Read a FITS header from a file to an internal structure.

Parameters:
filename   Name of the file to be read
Returns:
Pointer to newly allocated qfits_header or NULL in error case.

This function parses a FITS (main) header, and returns an allocated qfits_header object. The qfits_header object contains a linked-list of key "tuples". A key tuple contains:

  • A keyword
  • A value
  • A comment
  • An original FITS line (as read from the input file)
Direct access to the structure is not foreseen, use accessor functions in fits_h.h

Value, comment, and original line might be NULL pointers.

qfits_header * qfits_header_read_hdr ( char * filename )
 

Read a FITS header from a 'hdr' file.

Parameters:
filename   Name of the file to be read
Returns:
Pointer to newly allocated qfits_header or NULL in error case

This function parses a 'hdr' file, and returns an allocated qfits_header object. A hdr file is an ASCII format were the header is written with a carriage return after each line. The command dfits typically displays a hdr file.

qfits_header * qfits_header_readext ( char * filename,
int xtnum )
 

Read an extension header from a FITS file.

Parameters:
filename   Name of the FITS file to read
xtnum   Extension number to read, starting from 0.
Returns:
Newly allocated qfits_header structure.

Strictly similar to qfits_header_read() but reads headers from extensions instead. If the requested xtension is 0, this function calls qfits_header_read() to return the main header.

Returns NULL in case of error.

int qfits_header_sort ( qfits_header ** hdr )
 

Sort a FITS header.

Parameters:
hdr   Header to sort (modified)
Returns:
-1 in error case, 0 otherwise

char * qfits_header_to_memblock ( qfits_header * fh,
int * hsize )
 

Dump a fits header into a memory block.

Parameters:
fh   FITS header to dump
hsize   Size of the returned header, in bytes (output).
Returns:
1 newly allocated memory block containing the FITS header.

This function dumps a FITS header structure into a newly allocated memory block. The block is composed of characters, just as they would appear in a FITS file. This function is useful to make a FITS header in memory.

The returned block size is indicated in the passed output variable 'hsize'. The returned block must be deallocated using free().

void qfits_header_touchall ( qfits_header * hdr )
 

Touch all cards in a FITS header.

Parameters:
hdr   qfits_header to modify
Returns:
void

Touches all cards in a FITS header, i.e. all original FITS lines are freed and set to NULL. Useful when a header needs to be reformatted.

int qfits_is_boolean ( char * s )
 

Identify if a FITS value is boolean.

Parameters:
s   FITS value as a string
Returns:
int 0 or 1

Identifies if a FITS value is boolean.

int qfits_is_complex ( char * s )
 

Identify if a FITS value is complex.

Parameters:
s   FITS value as a string
Returns:
int 0 or 1

Identifies if a FITS value is complex.

int qfits_is_float ( char * s )
 

Identify if a FITS value is float.

Parameters:
s   FITS value as a string
Returns:
int 0 or 1

Identifies if a FITS value is float.

int qfits_is_int ( char * s )
 

Identify if a FITS value is an int.

Parameters:
s   FITS value as a string
Returns:
int 0 or 1

Identifies if a FITS value is an integer.

int qfits_is_paf_file ( char * filename )
 

returns 1 if file is in PAF format, 0 else.

Parameters:
filename   name of the file to check
Returns:
int 0, 1, or -1 Returns 1 if the file name corresponds to a valid PAF file. Returns 0 else. If the file does not exist, returns -1. Validity of the PAF file is checked with the presence of PAF.HDR.START at the beginning

int qfits_is_string ( char * s )
 

Identify if a FITS value is string.

Parameters:
s   FITS value as a string
Returns:
int 0 or 1

Identifies if a FITS value is a string.

int qfits_is_table ( char * filename,
int xtnum )
 

Identify a file as containing a FITS table in extension.

Parameters:
filename   Name of the FITS file to examine.
xtnum   Extension number to check (starting from 1).
Returns:
int 1 if the extension contains a table, 0 else.

Examines the requested extension and identifies the presence of a FITS table.

int qfits_loadpix ( qfitsloader * ql )
 

Load a pixel buffer for one image.

Parameters:
ql   Allocated and initialized qfitsloader control object.
Returns:
int 0 if Ok, -1 if error occurred.

This function performs a load of a pixel buffer into memory. It expects an allocated and initialized qfitsloader object in input. See qfitsloader_init() about initializing the object.

This function will fill up the ibuf/fbuf/dbuf field, depending on the requested pixel type (resp. int, float or double).

The returned buffer has been allocated using one of the special memory operators present in xmemory.c. To deallocate the buffer, you must call the version of free() offered by xmemory, not the usual system free(). It is enough to include "xmemory.h" in your code before you make calls to the pixel loader here.

FILE * qfits_paf_print_header ( char * filename,
char * paf_id,
char * paf_desc,
char * login_name,
char * datetime )
 

Open a new PAF file, output a default header.

Parameters:
filename   Name of the file to create.
paf_id   PAF identificator.
paf_desc   PAF description.
login_name   Login name
datetime   Date
Returns:
Opened file pointer.

This function creates a new PAF file with the requested file name. If another file already exists with the same name, it will be overwritten (if the file access rights allow it).

A default header is produced according to the VLT DICB standard. You need to provide an identificator (paf_id) of the producer of the file. Typically, something like "ISAAC/zero_point".

The PAF description (paf_desc) is meant for humans. Typically, something like "Zero point computation results".

This function returns an opened file pointer, ready to receive more data through fprintf's. The caller is responsible for fclose()ing the file.

char * qfits_paf_query ( char * filename,
char * key )
 

Query a PAF file for a value.

Parameters:
filename   Name of the PAF to query.
key   Name of the key to query.
Returns:
1 pointer to statically allocated string, or NULL.

This function parses a PAF file and returns the value associated to a given key, as a pointer to an internal statically allocated string. Do not try to free or modify the contents of the returned string!

If the key is not found, this function returns NULL.

int qfits_pixdump ( qfitsdumper * qd )
 

Dump a pixel buffer to an output FITS file in append mode.

Parameters:
qd   qfitsdumper control object.
Returns:
int 0 if Ok, -1 otherwise.

This function takes in input a qfitsdumper control object. This object must be allocated beforehand and contain valid references to the data to save, and how to save it.

The minimum fields to fill are:

  • filename: Name of the FITS file to dump to.
  • npix: Number of pixels in the buffer to be dumped.
  • ptype: Type of the passed buffer (PTYPE_FLOAT, PTYPE_INT, PTYPE_DOUBLE)
  • out_ptype: Requested FITS BITPIX for the output.
One of the following fields must point to the corresponding pixel buffer:

  • ibuf for an int pixel buffer (ptype=PTYPE_INT)
  • fbuf for a float pixel buffer (ptype=PTYPE_FLOAT)
  • dbuf for a double pixel buffer (ptype=PTYPE_DOUBLE)
This is a fairly low-level function, in the sense that it does not check that the output file already contains a proper header or even that the file it is appending to is indeed a FITS file. It will convert the pixel buffer to the requested BITPIX type and append the data to the file, without padding with zeros. See qfits_zeropad() about padding.

If the given output file name is "STDOUT" (all caps), the dump will be performed to stdout.

byte * qfits_pixdump_double ( double * buf,
int npix,
int ptype )
 

Convert a double pixel buffer to a byte buffer.

Parameters:
buf   Input double buffer.
npix   Number of pixels in the input buffer.
ptype   Requested output BITPIX type.
Returns:
1 pointer to a newly allocated byte buffer.

This function converts the given double buffer to a buffer of bytes suitable for dumping to a FITS file (i.e. big-endian, in the requested pixel type). The returned pointer must be deallocated using the free() function offered by xmemory.

byte * qfits_pixdump_float ( float * buf,
int npix,
int ptype )
 

Convert a float pixel buffer to a byte buffer.

Parameters:
buf   Input float buffer.
npix   Number of pixels in the input buffer.
ptype   Requested output BITPIX type.
Returns:
1 pointer to a newly allocated byte buffer.

This function converts the given float buffer to a buffer of bytes suitable for dumping to a FITS file (i.e. big-endian, in the requested pixel type). The returned pointer must be deallocated using the free() function offered by xmemory.

byte * qfits_pixdump_int ( int * buf,
int npix,
int ptype )
 

Convert an int pixel buffer to a byte buffer.

Parameters:
buf   Input int buffer.
npix   Number of pixels in the input buffer.
ptype   Requested output BITPIX type.
Returns:
1 pointer to a newly allocated byte buffer.

This function converts the given int buffer to a buffer of bytes suitable for dumping to a FITS file (i.e. big-endian, in the requested pixel type). The returned pointer must be deallocated using the free() function offered by xmemory.

double * qfits_pixin_double ( byte *,
int,
int,
double,
double )
 

Load a pixel buffer as doubles.

Parameters:
p_source   Pointer to source buffer (as bytes).
npix   Number of pixels to load.
bitpix   FITS BITPIX in original file.
bscale   FITS BSCALE in original file.
bzero   FITS BZERO in original file.
Returns:
1 pointer to a newly allocated buffer of npix doubles.

This function takes in input a pointer to a byte buffer as given in the original FITS file (big-endian format). It converts the buffer to an array of double (whatever representation is used for int by this platform is used) and returns the newly allocated buffer, or NULL if an error occurred.

The returned buffer must be deallocated using the free() offered by xmemory. It is enough to include "xmemory.h" before calling free on the returned pointer.

float * qfits_pixin_float ( byte *,
int,
int,
double,
double )
 

Load a pixel buffer as floats.

Parameters:
p_source   Pointer to source buffer (as bytes).
npix   Number of pixels to load.
bitpix   FITS BITPIX in original file.
bscale   FITS BSCALE in original file.
bzero   FITS BZERO in original file.
Returns:
1 pointer to a newly allocated buffer of npix floats.

This function takes in input a pointer to a byte buffer as given in the original FITS file (big-endian format). It converts the buffer to an array of float (whatever representation is used for floats by this platform is used) and returns the newly allocated buffer, or NULL if an error occurred.

The returned buffer must be deallocated using the free() offered by xmemory. It is enough to include "xmemory.h" before calling free on the returned pointer.

int * qfits_pixin_int ( byte *,
int,
int,
double,
double )
 

Load a pixel buffer as ints.

Parameters:
p_source   Pointer to source buffer (as bytes).
npix   Number of pixels to load.
bitpix   FITS BITPIX in original file.
bscale   FITS BSCALE in original file.
bzero   FITS BZERO in original file.
Returns:
1 pointer to a newly allocated buffer of npix ints.

This function takes in input a pointer to a byte buffer as given in the original FITS file (big-endian format). It converts the buffer to an array of int (whatever representation is used for int by this platform is used) and returns the newly allocated buffer, or NULL if an error occurred.

The returned buffer must be deallocated using the free() offered by xmemory. It is enough to include "xmemory.h" before calling free on the returned pointer.

char * qfits_pretty_string ( char * s )
 

Clean out a FITS string value.

Parameters:
s   pointer to allocated FITS value string.
Returns:
pointer to statically allocated character string

From a string FITS value like 'marvin o''hara', remove head and tail quotes, replace double '' with simple ', trim blanks on each side, and return the result in a statically allocated area.

Examples:

  • ['o''hara'] becomes [o'hara]
  • [' H '] becomes [H]
  • ['1.0 '] becomes [1.0]

char * qfits_query_card ( char * filename,
char * keyword )
 

Query a card in a FITS (main) header by a given key.

Parameters:
filename   Name of the FITS file to check.
keyword   Where to read a card in the header.
Returns:
Allocated string containing the card or NULL

unsigned char * qfits_query_column ( qfits_table * th,
int colnum,
int * selection )
 

Extract data from a column in a FITS table.

Parameters:
th   Allocated qfits_table
colnum   Number of the column to extract (from 0 to colnum-1)
selection   boolean array to define the selected rows
Returns:
unsigned char array

If selection is NULL, select the complete column.

Extract a column from a FITS table and return the data as a bytes array. The returned array type and size are determined by the column object in the qfits_table and by the selection parameter.

Returned array size in bytes is: nbselected * col->natoms * col->atom_size

Numeric types are correctly understood and byte-swapped if needed, to be converted to the local machine type.

NULL values have to be handled by the caller.

The returned buffer has been allocated using one of the special memory operators present in xmemory.c. To deallocate the buffer, you must call the version of free() offered by xmemory, not the usual system free(). It is enough to include "xmemory.h" in your code before you make calls to the pixel loader here.

void * qfits_query_column_data ( qfits_table * th,
int colnum,
int * selection,
void * null_value )
 

Extract binary data from a column in a FITS table.

Parameters:
th   Allocated qfits_table
colnum   Number of the column to extract (from 0 to colnum-1)
selection   bollean array to identify selected rows
null_value   Value to return when a NULL value comes
Returns:
Pointer to void *

Extract a column from a FITS table and return the data as a generic void* array. The returned array type and size are determined by the column object in the qfits_table.

Returned array size in bytes is: nb_selected * col->atom_nb * col->atom_size

NULL values are recognized and replaced by the specified value.

The returned buffer has been allocated using one of the special memory operators present in xmemory.c. To deallocate the buffer, you must call the version of free() offered by xmemory, not the usual system free(). It is enough to include "xmemory.h" in your code before you make calls to the pixel loader here.

int * qfits_query_column_nulls ( qfits_table * th,
int colnum,
int * selection,
int * nb_vals,
int * nb_nulls )
 

Detect NULL values in a column.

Parameters:
th   Allocated qfits_table
colnum   Number of the column to check (from 0 to colnum-1)
selection   Array to identify selected rows
nb_vals   Gives the size of the output array
nb_nulls   Gives the number of detected null values
Returns:
array with 1 for NULLs and 0 for non-NULLs

unsigned char * qfits_query_column_seq ( qfits_table * th,
int colnum,
int start_ind,
int nb_rows )
 

Extract consequtive values from a column in a FITS table.

Parameters:
th   Allocated qfits_table
colnum   Number of the column to extract (from 0 to colnum-1)
start_ind   Index of the first row (0 for the first)
nb_rows   Number of rows to extract
Returns:
unsigned char array Does the same as qfits_query_column() but on a consequtive sequence of rows Spares the overhead of the selection object allocation

void * qfits_query_column_seq_data ( qfits_table * th,
int colnum,
int start_ind,
int nb_rows,
void * null_value )
 

Extract binary data from a column in a FITS table.

Parameters:
th   Allocated qfits_table
colnum   Number of the column to extract (from 0 to colnum-1)
start_ind   Index of the first row (0 for the first)
nb_rows   Number of rows to extract
null_value   Value to return when a NULL value comes
Returns:
Pointer to void * Does the same as qfits_query_column_data() but on a consequtive sequence of rows. Spares the overhead of the selection object allocation

char * qfits_query_ext ( char * filename,
char * keyword,
int xtnum )
 

Retrieve the value of a keyin a FITS extension header.

Parameters:
filename   name of the FITS file to browse.
keyword   name of the FITS key to look for.
xtnum   xtension number
Returns:
pointer to statically allocated character string

Same as qfits_query_hdr but for extensions. xtnum starts from 1 to the number of extensions. If xtnum is zero, this function is strictly identical to qfits_query_hdr().

char * qfits_query_hdr ( char * filename,
char * keyword )
 

Retrieve the value of a key in a FITS header.

Parameters:
filename   Name of the FITS file to browse
keyword   Name of the keyword to find
Returns:
pointer to statically allocated character string

Provide the name of a FITS file and a keyword to look for. The input file is memory-mapped and the first keyword matching the requested one is located. The value corresponding to this keyword is copied to a statically allocated area, so do not modify it or free it.

The input keyword is first converted to upper case and expanded to the HIERARCH scheme if given in the shortFITS notation.

This function is pretty fast due to the mmapping. Due to buffering on most Unixes, it is possible to call many times this function in a row on the same file and do not suffer too much from performance problems. If the file contents are already in the cache, the file will not be re-opened every time.

It is possible, though, to modify this function to perform several searches in a row. See the source code.

Returns NULL in case the requested keyword cannot be found.

int qfits_query_n_ext ( char * filename )
 

Counts the number of extensions in a FITS file.

Parameters:
filename   Name of the FITS file to browse.
Returns:
int

Counts how many extensions are in the file. Returns 0 if no extension is found, and -1 if an error occurred.

int qfits_query_nplanes ( char * filename,
int extnum )
 

Counts the number of planes in a FITS extension.

Parameters:
filename   Name of the FITS file to browse.
exnum   Extensin number
Returns:
int Counts how many planes are in the extension. Returns 0 if no plane is found, and -1 if an error occurred.

int qfits_replace_card ( char * filename,
char * keyword,
char * substitute )
 

Replace a card in a FITS (main) header by a given card.

Parameters:
filename   Name of the FITS file to modify.
keyword   Where to substitute a card in the header.
substitute   What to replace the line with.
Returns:
int 0 if Ok, -1 otherwise

Replaces a whole card (80 chars) in a FITS header by a given FITS line (80 chars). The replacing line is assumed correctly formatted and containing at least 80 characters. The file is modified: it must be accessible in read/write mode.

The input keyword is first converted to upper case and expanded to the HIERARCH scheme if given in the shortFITS notation.

Returns 0 if everything worked Ok, -1 otherwise.

int qfits_save_table_hdrdump ( void ** array,
qfits_table * table,
qfits_header * fh )
 

Save a table to a FITS file with a given FITS header.

Parameters:
array   Data array.
table   table
fh   FITS header to insert in the output file.
Returns:
-1 in error case, 0 otherwise

int qfits_table_append_xtension ( FILE * outfile,
qfits_table * t,
void ** data )
 

Appends a std extension header + data to a FITS table file.

Parameters:
outfile   Pointer to (opened) file ready for writing.
t   Pointer to qfits_table
data   Table data to write
Returns:
int 0 if Ok, -1 otherwise

Dumps a FITS table to a file. The whole table described by qfits_table, and the data arrays contained in 'data' are dumped to the file. An extension header is produced with all keywords needed to describe the table, then the data is dumped to the file. The output is then padded to reach a multiple of 2880 bytes in size. Notice that no main header is produced, only the extension part.

int qfits_table_append_xtension_hdr ( FILE * outfile,
qfits_table * t,
void ** data,
qfits_header * hdr )
 

Appends a specified extension header + data to a FITS table file.

Parameters:
outfile   Pointer to (opened) file ready for writing.
t   Pointer to qfits_table
data   Table data to write
hdr   Specified extension header
Returns:
int 0 if Ok, -1 otherwise

Dumps a FITS table to a file. The whole table described by qfits_table, and the data arrays contained in 'data' are dumped to the file following the specified fits header. The output is then padded to reach a multiple of 2880 bytes in size. Notice that no main header is produced, only the extension part.

void qfits_table_close ( qfits_table * t )
 

Free a FITS table and associated pointers.

Parameters:
t   qfits_table to free
Returns:
void Frees all memory associated to a qfits_table structure.

qfits_header * qfits_table_ext_header_default ( qfits_table * )
 

Generate a default extension header to store tables.

Returns:
the header object

char * qfits_table_field_to_string ( qfits_table * table,
int col_id,
int row_id,
int use_zero_scale )
 

given a col and a row, find out the string to write for display.

Parameters:
table   table structure
col_id   col id (0 -> nbcol-1)
row_id   row id (0 -> nrow-1)
use_zero_scale   Flag to use or not zero and scale
Returns:
the string to write

qfits_table * qfits_table_new ( char * filename,
int table_type,
int table_width,
int nb_cols,
int nb_raws )
 

Table object constructor.

Parameters:
filename   Name of the FITS file associated to the table
table_type   Type of the table (QFITS_ASCIITABLE or QFITS_BINTABLE)
table_width   Width in bytes of the table
nb_cols   Number of columns
nb_raws   Number of raws
Returns:
The table object The columns are also allocated. The object has to be freed with qfits_table_close()

qfits_table * qfits_table_open ( char * filename,
int xtnum )
 

Read a FITS extension.

Parameters:
filename   Name of the FITS file to examine.
xtnum   Extension number to read (starting from 1).
Returns:
Pointer to newly allocated qfits_table structure.

Read a FITS table from a given file name and extension, and return a newly allocated qfits_table structure.

qfits_header * qfits_table_prim_header_default ( void )
 

Generate a default primary header to store tables.

Returns:
the header object

long qfits_time_now ( void )
 

Returns the current time as a long (HHMMSSCC).

Returns:
The current time as a long number.

Returns the current time as a long value (HHMMSSCC). If the system clock does not return centiseconds, these are set to zero. Example: 15:36:12.84 is returned as 15361284

char* qfits_version ( void )
 

void qfits_zeropad ( char * filename )
 

Pad an existing file with zeros to a multiple of 2880.

Parameters:
filename   Name of the file to pad.
Returns:
void

This function simply pads an existing file on disk with enough zeros for the file size to reach a multiple of 2880, as required by FITS.

int qfitsloader_init ( qfitsloader * ql )
 

Initialize a qfitsloader control object.

Parameters:
ql   qfitsloader object to initialize.
Returns:
int 0 if Ok, -1 if error occurred.

This function expects a qfitsloader object with a number of input fields correctly filled in. The minimum fields to set are:

  • filename: Name of the file to examine.
  • xtnum: Extension number to examine (0 for main section).
  • pnum: Plane number in the requested extension.
You can go ahead with these fields only if you only want to get file information for this plane in this extension. If you want to later load the plane, you must additionally fill the 'ptype' field to a correct value (PTYPE_INT, PTYPE_FLOAT, PTYPE_DOUBLE) before calling qfits_loadpix() so that it knows which conversion to perform.

This function is basically a probe sent on a FITS file to ask qfits if loading these data would be Ok or not. The actual loading is performed by qfits_loadpix() afterwards.