5.1 Creating New Files

When creating a new output file on magnetic disk with fits_create_file the following features are supported.

• Overwriting, or 'Clobbering' an Existing File

  If the filename is preceded by an exclamation point (!) then if that file already exists it will be deleted prior to creating the new FITS file. Otherwise if there is an existing file with the same name, CFITSIO will not overwrite the existing file and will return an error status code. Note that the exclamation point is a special UNIX character, so if it is used on the command line rather than entered at a task prompt, it must be preceded by a backslash to force the UNIX shell to pass it verbatim to the application program.

• Compressed Output Files

  If the output disk file name ends with the suffix '.gz', then CFITSIO will compress the file using the gzip compression algorithm before writing it to disk. This can reduce the amount of disk space used by the file. Note that this feature requires that the uncompressed file be constructed in memory before it is compressed and written to disk, so it can fail if there is insufficient available memory.

  One can also specify that any images written to the output file should be compressed using the newly developed `tile-compression' algorithm by appending `[compress]' to the name of the disk file (as in myfile.fits[compress]). Refer to the CFITSIO User's Reference Guide for more information about this new image compression format.

• Using a Template to Create a New FITS File

  The structure of any new FITS file that is to be created may be defined in an ASCII template file. If the name of the template file is appended to the name of the FITS file itself, enclosed in parenthesis (e.g., 'newfile.fits(template.txt)') then CFITSIO will create a FITS file with that structure before opening it for the application to use. The template file basically defines the dimensions and data type of the primary array and any IMAGE extensions, and the names and data types of the columns in any ASCII or binary table extensions. The template file can also be used to define any optional keywords that should be written in any of the HDU headers. The image pixel values and table entry values are all initialized to zero. The application program can then write actual data into the HDUs. See the CFITSIO Reference Guide for for a complete description of the template file syntax.

• Creating a Temporary Scratch File in Memory

  It is sometimes useful to create a temporary output file when testing an application program. If the name of the file to be created is specified as mem: then CFITSIO will create the file in memory where it will persist only until the program closes the file. Use of this mem: output file usually enables the program to run faster, and of course the output file does not use up any disk space.