5.3 HDU Access Routines

The following functions perform operations on Header-Data Units (HDUs) as a whole.

1

Move to a different HDU in the file. The first routine moves to a specified absolute HDU number (starting with 1 for the primary array) in the FITS file, and the second routine moves a relative number HDUs forward or backward from the current HDU. A null pointer may be given for the hdutype parameter if it's value is not needed. The third routine moves to the (first) HDU which has the specified extension type and EXTNAME and EXTVER keyword values (or HDUNAME and HDUVER keywords). The extname parameter may contain wildcards, as accepted by fits_compare_str(). The hdutype parameter may have a value of IMAGE_HDU, ASCII_TBL, BINARY_TBL, or ANY_HDU where ANY_HDU means that only the extname and extver values will be used to locate the correct extension. If the input value of extver is 0 then the EXTVER keyword is ignored and the first HDU with a matching EXTNAME (or HDUNAME) keyword will be found. If no matching HDU is found in the file then the current HDU will remain unchanged and a status = BAD_HDU_NUM will be returned.

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

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

  int fits_movnam_hdu / ffmnhd
      (fitsfile *fptr, int hdutype, char *extname, int extver, > int *status)

2

Return the total number of HDUs in the FITS file. This returns the number of completely defined HDUs in the file. If a new HDU has just been added to the FITS file, then that last HDU will only be counted if it has been closed, or if data has been written to the HDU. The current HDU remains unchanged by this routine.

  int fits_get_num_hdus / ffthdu
      (fitsfile *fptr, > int *hdunum, int *status)

3

Return the number of the current HDU (CHDU) in the FITS file (where the primary array = 1). This function returns the HDU number rather than a status value.

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

4

Return the type of the current HDU in the FITS file. The possible values for hdutype are: IMAGE_HDU, ASCII_TBL, or BINARY_TBL.

  int fits_get_hdu_type / ffghdt
      (fitsfile *fptr, > int *hdutype, int *status)

5

Copy all or part of the HDUs in the FITS file associated with infptr and append them to the end of the FITS file associated with outfptr. If 'previous' is true (not 0), then any HDUs preceding the current HDU in the input file will be copied to the output file. Similarly, 'current' and 'following' determine whether the current HDU, and/or any following HDUs in the input file will be copied to the output file. Thus, if all 3 parameters are true, then the entire input file will be copied. On exit, the current HDU in the input file will be unchanged, and the last HDU in the output file will be the current HDU.

  int fits_copy_file / ffcpfl
      (fitsfile *infptr, fitsfile *outfptr, int previous, int current,
          int following, > int *status)

6

Copy the current HDU from the FITS file associated with infptr and append it to the end of the FITS file associated with outfptr. Space may be reserved for MOREKEYS additional keywords in the output header.

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

7

Write the current HDU in the input FITS file to the output FILE stream (e.g., to stdout).

  int fits_write_hdu / ffwrhdu
      (fitsfile *infptr, FILE *stream, > int *status)

8

Copy the header (and not the data) from the CHDU associated with infptr to the CHDU associated with outfptr. If the current output HDU is not completely empty, then the CHDU will be closed and a new HDU will be appended to the output file. An empty output data unit will be created with all values initially = 0).

  int fits_copy_header / ffcphd
      (fitsfile *infptr, fitsfile *outfptr, > int *status)

9

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. In the case of deleting the primary array (the first HDU in the file) then the current primary array will be replace by a null primary array containing the minimum set of required keywords and no data. If there are more extensions in the file following the one that is deleted, then the the CHDU will be redefined 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 returns the type of the new CHDU. A null pointer may be given for hdutype if the returned value is not needed.

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