next up previous contents FITSIO Home
Next: Header Keyword Read/Write Routines Up: Basic CFITSIO Interface Routines Previous: FITS File Access Routines   Contents

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 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. The current HDU remains unchanged.

  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
Create a new primary array or IMAGE extension with a specified datatype and size. 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)

6
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 fewer 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)

7
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)

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)


next up previous contents FITSIO Home
Next: Header Keyword Read/Write Routines Up: Basic CFITSIO Interface Routines Previous: FITS File Access Routines   Contents