HDU-Level Operations

The following routines perform operations on entire HDUs: move, create, insert, copy, and delete HDUs.

1

Move to a specified (absolute) HDU in the FITS file. When a FITS file is first opened or created it is automatically positioned to the first HDU (the primary array) in the file which has hdunum = 1.

  int fits_movabs_hdu / ffmahd
      (fitsfile *fptr, int hdunum, > int *hdutype, int *status)

2

Move a relative number of HDUs forward or backwards in the FITS file.

  int fits_movrel_hdu / ffmrhd
      (fitsfile *fptr, int nmove, > int *hdutype, int *status)

3

Get the number of the current HDU in the FITS file (primary array = 1). This routine returns the HDU number rather than a status value.

  int fits_get_hdunum / ffghdn
      (fitsfile *fptr, > int *hdunum)

4

Get the byte offsets in the file to the start and end of the CHDU. The difference between these 2 values gives the size of the CHDU. If the CHDU is the last HDU in the file, then the ending offset is also equal to the size of the entire FITS file.

  int fits_get_hduaddr / ffghad
       (fitsfile *fptr, > long *chduaddr, long *nextaddr)

5

Create a new primary array if a new empty FITS file has just been created, otherwise append a new IMAGE extension following the current HDU. Refer to Chapter 9 for a list of pre-defined bitpix values. This routine simply combines calls to ffcrhd and ffphps.

  int fits_create_img / ffcrim
      ( fitsfile *fptr, int bitpix, int naxis, long *naxes, > int *status)

6

Create (append) a new table extension following the current HDU. This routine simply combines calls to ffcrhd and ffphtb or ffphbn. The type of table is specified by the tbltype parameter which can have symbolic constant values of ASCII_TBL or BINARY_TBL. See Chapter 9 for a list of allowed tform values.

  int fits_create_tbl / ffcrtb
      (fitsfile *fptr, int tbltype, long naxis2, int tfields, char **ttype,
       char **tform, char **tunit, char *extname, int *status)

7

Create (append) a new empty HDU following the last extension that has been previously accessed by the program. This will overwrite any later extensions that may exist in the FITS file but which have not been accessed. For example, if an existing FITS file contains a primary array plus 5 extensions and a program (1) opens the FITS file, (2) moves to extension 4, (3) moves back to the primary array, and (4) then calls ffcrhd, then the new extension will be written following the 4th extension, overwriting the existing 5th extension.

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

8

Insert a new IMAGE 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 image extension will simply be appended to the end of the file. The new extension 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)

9

Insert a new ASCII 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. The new extension will become the CHDU. See Chapter 9 for a list of allowed tform values.

  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)

10

Insert a new 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 bintable extension will simply be appended to the end of the file. If there are following extensions 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. The new extension will become the CHDU. See Chapter 9 for a list of allowed tform values.

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

11

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 new image.

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

12

Delete the CHDU in the FITS file. Any following HDUs will be shifted forward in the file, to fill in the gap created by the deleted HDU. This routine will only delete extensions; the primary array (the first HDU in the file) cannot be deleted. The physical size of the FITS file will not change and the end of the file will be padded out with zeros to fill in the space left after the CHDU is deleted. If there are more extensions in the file following the one that is deleted, then the the CHDU will be defined to point to the following extension. If there are no following extensions then the CHDU will be redefined to point to the previous HDU. The output HDUTYPE parameter indicates the type of the new CHDU after the previous CHDU has been deleted.

  int fits_delete_hdu / ffdhdu
      (fitsfile *fptr, > int *hdutype, int *status)

13

Copy the entire CHDU from the FITS file associated with infptr to the CHDU of the FITS file associated with outfptr. The output HDU must be empty and not already contain any keywords. Space will be reserved for MOREKEYS additional keywords in the output header if there is not already enough space.

  int fits_copy_hdu / ffcopy
      (fitsfile *infptr, fitsfile *outfptr, int morekeys, > int *status)

14

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 ffcopy, but it may also be useful in certain application programs which 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)

15

This routine forces CFITSIO to scan the current header keywords that define the structure of the HDU (such as the NAXISn, PCOUNT and GCOUNT keywords) so that it can initialize the internal buffers that describe the HDU structure. This routine is useful for reinitializing the structure of an HDU, e.g., if the number of rows in a table, as specified by the NAXIS2 keyword, has been modified from its initial value. 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)