Output File Name when Opening an Existing File

An optional output filename may be specified in parentheses immediately following base file name to be opened. In a number of instances CFITSIO will create a temporary copy in memory of the input FITS file before it is opened and passed to the application program. This happens by default when opening a network FTP or HTTP-type file, when reading a compressed FITS file on a local disk, when reading from the stdin stream, or when a column filter, row filter, or binning specifier is included as part of the input file specification. The local machine must then be able to hold a copy of the whole FITS file in memory, otherwise CFITSIO will exit with an error. If this is a problem (e.g., on machines with a small amount of memory, or when reading very large files) then the output file specifier may be used to give the name of a local disk file that CFITSIO will create and use instead of trying to create a copy of the file in memory.

Thus, if the input filename to CFITSIO is:

    file1.fits.gz(file2.fits)

then CFITSIO will uncompress `file1.fits.gz' into the local disk file `file2.fits' before opening it. CFITSIO does not automatically delete the output file, so it will still exist after the application program exits.

The output file specifier is also useful when reading FTP or HTTP-type FITS files since it can be used to create a local disk copy of the file that can be reused in the future. If the output file name = `*' then a local file with the same name as the network file will be created. Note that CFITSIO will behave differently depending on whether the remote file is compressed or not as shown by the following examples:

• `ftp://remote.machine/tmp/myfile.fits.gz(*)' - the remote compressed file is copied to the local compressed file `myfile.fits.gz', which is then uncompressed in local memory before being opened and passed to the application program.

• `ftp://remote.machine/tmp/myfile.fits.gz(myfile.fits)' - the remote compressed file is copied and uncompressed into the local file `myfile.fits'. This example requires less local memory than the previous example since the file is uncompressed on disk instead of in memory.

• `ftp://remote.machine/tmp/myfile.fits(myfile.fits.gz)' - this will usually produce an error since CFITSIO itself cannot compress files.

The exact behavior of CFITSIO in the latter case depends on the type of ftp server running on the remote machine and how it is configured. In some cases, if the file `myfile.fits.gz' exists on the remote machine, then the server will copy it to the local machine. In other cases the ftp server will automatically create and transmit a compressed version of the file if only the uncompressed version exists. This can get rather confusing, so users should use a certain amount of caution when using the output file specifier with FTP or HTTP file types, to make sure they get the behavior that they expect.