6.1 FITS File Open and Close Subroutines:

1

Open an existing FITS file with readonly or readwrite access. The FTDKOPN routine simply opens the specified file without trying to interpret the filename using the extended filename syntax. FTDOPN opens the file and also moves to the first HDU containing significant data, if no specific HDU is specified as part of the filename. FTTOPN and FTIOPN are similar except that they will move to the first table HDU or image HDU, respectively, if a HDU name or number is not specified as part of the filename.

        FTOPEN(unit,filename,rwmode, > blocksize,status)
        FTDKOPN(unit,filename,rwmode, > blocksize,status)

        FTDOPN(unit,filename,rwmode, > status)
        FTTOPN(unit,filename,rwmode, > status)
        FTIOPN(unit,filename,rwmode, > status)

2

Open an existing FITS file with readonly or readwrite access and move to a following extension, if one was specified as part of the filename. (e.g., 'filename.fits+2' or 'filename.fits[2]' will move to the 3rd HDU in the file). Note that this routine differs from FTOPEN in that it does not have the redundant blocksize argument.

        FTNOPN(unit,filename,rwmode, > status)

3

Reopen a FITS file that was previously opened with FTOPEN, FTNOPN, or FTINIT. The newunit number may then be treated as a separate file, and one may simultaneously read or write to 2 (or more) different extensions in the same file. The FTOPEN and FTNOPN routines (above) automatically detects cases where a previously opened file is being opened again, and then internally call FTREOPEN, so programs should rarely need to explicitly call this routine.

       FTREOPEN(unit, > newunit, status)

4

Open and initialize a new empty FITS file. The FTDKINIT routine simply creates the specified file without trying to interpret the filename using the extended filename syntax.

       FTINIT(unit,filename,blocksize, > status)
       FTDKINIT(unit,filename,blocksize, > status)

5

Create a new FITS file, using a template file to define its initial size and structure. The template may be another FITS HDU or an ASCII template file. If the input template file name is blank, then this routine behaves the same as FTINIT. The currently supported format of the ASCII template file is described under the fits_parse_template routine (in the general Utilities section), but this may change slightly later releases of CFITSIO.

       FTTPLT(unit, filename, tplfilename, > status)

6

Flush internal buffers of data to the output FITS file previously opened with ftopen or ftinit. The routine usually never needs to be called, but doing so will ensure that if the program subsequently aborts, then the FITS file will have at least been closed properly.

        FTFLUS(unit, > status)

7

Close a FITS file previously opened with ftopen or ftinit

        FTCLOS(unit, > status)

8

Close and DELETE a FITS file previously opened with ftopen or ftinit. This routine may be useful in cases where a FITS file is created, but an error occurs which prevents the complete file from being written.

        FTDELT(unit, > status)

9

Get the value of an unused I/O unit number which may then be used as input to FTOPEN or FTINIT. This routine searches for the first unused unit number in the range from with 99 down to 50. This routine just keeps an internal list of the allocated unit numbers and does not physically check that the Fortran unit is available (to be compatible with the SPP version of FITSIO). Thus users must not independently allocate any unit numbers in the range 50 - 99 if this routine is also to be used in the same program. This routine is provided for convenience only, and it is not required that the unit numbers used by FITSIO be allocated by this routine.

        FTGIOU( > iounit, status)

10

Free (deallocate) an I/O unit number which was previously allocated with FTGIOU. All previously allocated unit numbers may be deallocated at once by calling FTFIOU with iounit = -1.

        FTFIOU(iounit, > status)

11

Return the Fortran unit number that corresponds to the C fitsfile pointer value, or vice versa. These 2 C routines may be useful in mixed language programs where both C and Fortran subroutines need to access the same file. For example, if a FITS file is opened with unit 12 by a Fortran subroutine, then a C routine within the same program could get the fitfile pointer value to access the same file by calling 'fptr = CUnit2FITS(12)'. These routines return a value of zero if an error occurs.

      int       CFITS2Unit(fitsfile *ptr);
      fitsfile* CUnit2FITS(int unit);

11

Parse the input filename and return the HDU number that would be moved to if the file were opened with FTNOPN. The returned HDU number begins with 1 for the primary array, so for example, if the input filename = `myfile.fits[2]' then hdunum = 3 will be returned. FITSIO does not open the file to check if the extension actually exists if an extension number is specified. If an extension *name* is included in the file name specification (e.g. `myfile.fits[EVENTS]' then this routine will have to open the FITS file and look for the position of the named extension, then close file again. This is not possible if the file is being read from the stdin stream, and an error will be returned in this case. If the filename does not specify an explicit extension (e.g. 'myfile.fits') then hdunum = -99 will be returned, which is functionally equivalent to hdunum = 1. This routine is mainly used for backward compatibility in the ftools software package and is not recommended for general use. It is generally better and more efficient to first open the FITS file with FTNOPN, then use FTGHDN to determine which HDU in the file has been opened, rather than calling FTEXTN followed by a call to FTNOPN.

        FTEXTN(filename, > nhdu, status)

12

Return the name of the opened FITS file.

        FTFLNM(unit, > filename, status)

13

Return the I/O mode of the open FITS file (READONLY = 0, READWRITE = 1).

        FTFLMD(unit, > iomode, status)

14

Return the file type of the opened FITS file (e.g. 'file://', 'ftp://', etc.).

        FTURLT(unit, > urltype, status)

15

Parse the input filename or URL into its component parts: the file type (file://, ftp://, http://, etc), the base input file name, the name of the output file that the input file is to be copied to prior to opening, the HDU or extension specification, the filtering specifier, the binning specifier, and the column specifier. Blank strings will be returned for any components that are not present in the input file name.

       FTIURL(filename, > filetype, infile, outfile, extspec, filter,
               binspec, colspec, status)

16

Parse the input file name and return the root file name. The root name includes the file type if specified, (e.g. 'ftp://' or 'http://') and the full path name, to the extent that it is specified in the input filename. It does not include the HDU name or number, or any filtering specifications.

       FTRTNM(filename, > rootname, status)

16

Test if the input file or a compressed version of the file (with a .gz, .Z, .z, or .zip extension) exists on disk. The returned value of the 'exists' parameter will have 1 of the 4 following values:

   2:  the file does not exist, but a compressed version does exist
   1:  the disk file does exist
   0:  neither the file nor a compressed version of the file exist
  -1:  the input file name is not a disk file (could be a ftp, http,
       smem, or mem file, or a file piped in on the STDIN stream)

      FTEXIST(filename, > exists, status);