HDU Access Routines

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

1

Move to a specified absolute HDU number 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. A null pointer may be given for the hdutype parameter if it's value is not needed.  

  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 from the current position. A null pointer may be given for the hdutype parameter if it's value is not needed.  

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

3

Move to the (first) HDU which has the specified extension type and EXTNAME and EXTVERS keyword values. 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 extvers values will be used to locate the correct extension. If the input value of extvers is 0 then the EXTVERS keyword is ignored and the first HDU with a matching EXTNAME 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_movnam_hdu / ffmnhd
      (fitsfile *fptr, int hdutype, char *extname, int extvers, > int *status)

4

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

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

5

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)

6

Return the total number of HDUs in the FITS file. The CHDU remains unchanged.  

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

7

Create a new primary array or IMAGE extension. If the FITS file is currently empty then a primary array is created, otherwise a new IMAGE extension is appended to the file.  

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

8

Create a new ASCII or bintable table extension. If the FITS file is currently empty then a dummy primary array will be created before appending the table extension to it. The tbltype parameter defines the type of table and can have values of ASCII_TBL or BINARY_TBL. The naxis2 parameter gives the initial number of rows to be created in the table, and should normally be set = 0. CFITSIO will automatically increase the size of the table as additional rows are written. A non-zero number of rows may be specified to reserve space for that many rows, even if a few number of rows will be written. The tunit and extname parameters are optional and a null pointer may be given if they are not defined. The FITS Standard recommends that only letters, digits, and the underscore character be used in column names (the ttype parameter) with no embedded spaces). Trailing blank characters are not significant. It is recommended that all the column names in a given table be unique within the first 8 characters, and strongly recommended that the names be unique within the first 16 characters.  

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

9

Copy the CHDU 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)

10

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 necessarily be reduced. 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)