9.2 HDU Access Routines

1

Get the byte offsets in the FITS file to the start of the header and the start and end of the data in the CHDU. The difference between headstart and dataend equals the size of the CHDU. If the CHDU is the last HDU in the file, then dataend is also equal to the size of the entire FITS file. Null pointers may be input for any of the address parameters if their values are not needed. The fits_get_hduaddr routine is obsolete and should no longer be used. The newer fits_get_hduoff routine uses the 'off_t' datatype which can support offsets in large files greater than 2.1GB in size.  

  int fits_get_hduoff / ffghof
       (fitsfile *fptr, > off_t *headstart, off_t *datastart, off_t *dataend,
        int *status)

  int fits_get_hduaddr / ffghad  (OBSOLETE routine)
       (fitsfile *fptr, > long *headstart, long *datastart, long *dataend,
        int *status)

2

Create (append) a new empty HDU at the end of the FITS file. This is now the CHDU but it is completely empty and has no header keywords. It is recommended that fits_create_img or fits_create_tbl be used instead of this routine.  

  int fits_create_hdu / ffcrhd
      (fitsfile *fptr, > int *status)

3

Insert a new IMAGE extension immediately following the CHDU, or insert a new Primary Array at the beginning of the file. Any following extensions in the file will be shifted down to make room for the new extension. If the CHDU is the last HDU in the file then the new image extension will simply be appended to the end of the file. One can force a new primary array to be inserted at the beginning of the FITS file by setting status = PREPEND_PRIMARY prior to calling the routine. In this case the old primary array will be converted to an IMAGE extension. The new extension (or primary array) will become the CHDU. Refer to Chapter 9 for a list of pre-defined bitpix values.  

  int fits_insert_img / ffiimg
      (fitsfile *fptr, int bitpix, int naxis, long *naxes, > int *status)

4

Insert a new ASCII or binary table extension immediately following the CHDU. Any following extensions will be shifted down to make room for the new extension. If there are no other following extensions then the new table extension will simply be appended to the end of the file. If the FITS file is currently empty then this routine will create a dummy primary array before appending the table to it. The new extension will become the CHDU. The tunit and extname parameters are optional and a null pointer may be given if they are not defined. When inserting an ASCII table with fits_insert_atbl, a null pointer may given for the *tbcol parameter in which case each column of the table will be separated by a single space character. Similarly, if the input value of rowlen is 0, then CFITSIO will calculate the default rowlength based on the tbcol and ttype values. When inserting a binary table with fits_insert_btbl, if there are following extensions in the file and if the table contains variable length array columns then pcount must specify the expected final size of the data heap, otherwise pcount must = 0.    

  int fits_insert_atbl / ffitab
      (fitsfile *fptr, long rowlen, long nrows, int tfields, char *ttype[],
       long *tbcol, char *tform[], char *tunit[], char *extname, > int *status)

  int fits_insert_btbl / ffibin
      (fitsfile *fptr, long nrows, int tfields, char **ttype,
      char **tform, char **tunit, char *extname, long pcount, > int *status)

5

Modify the size, dimensions, and/or datatype of the current primary array or image extension. If the new image, as specified by the input arguments, is larger than the current existing image in the FITS file then zero fill data will be inserted at the end of the current image and any following extensions will be moved further back in the file. Similarly, if the new image is smaller than the current image then any following extensions will be shifted up towards the beginning of the FITS file and the image data will be truncated to the new size. This routine rewrites the BITPIX, NAXIS, and NAXISn keywords with the appropriate values for the new image.  

  int fits_resize_img / ffrsim
      (fitsfile *fptr, int bitpix, int naxis, long *naxes, > int *status)

6

Copy the data (and not the header) from the CHDU associated with infptr to the CHDU associated with outfptr. This will overwrite any data previously in the output CHDU. This low level routine is used by fits_copy_hdu, but it may also be useful in certain application programs that want to copy the data from one FITS file to another but also want to modify the header keywords. The required FITS header keywords which define the structure of the HDU must be written to the output CHDU before calling this routine.  

  int fits_copy_data / ffcpdt
      (fitsfile *infptr, fitsfile *outfptr, > int *status)

7

This routine forces CFITSIO to rescan the current header keywords that define the structure of the HDU (such as the NAXIS and BITPIX keywords) so that it reinitializes the internal buffers that describe the HDU structure. This routine is useful for reinitializing the structure of an HDU if any of the required keywords (e.g., NAXISn) have been modified. In practice it should rarely be necessary to call this routine because CFITSIO internally calls it in most situations.  

  int fits_set_hdustruc / ffrdef
      (fitsfile *fptr, > int *status)   (DEPRECATED)