5.2 Opening Existing Files

When opening a file with fits_open_file, CFITSIO can read a variety of different input file formats and is not restricted to only reading FITS format files from magnetic disk. The following types of input files are all supported:

• FITS files compressed with zip, gzip or compress

  If CFITSIO cannot find the specified file to open it will automatically look for a file with the same rootname but with a .gz, .zip, or .Z extension. If it finds such a compressed file, it will allocate a block of memory and uncompress the file into that memory space. The application program will then transparently open this virtual FITS file in memory. Compressed files can only be opened with 'readonly', not 'readwrite' file access.

• FITS files on the internet, using ftp or http URLs

  Simply provide the full URL as the name of the file that you want to open. For example,
  ftp://heasarc.gsfc.nasa.gov/software/fitsio/c/testprog.std
  will open the CFITSIO test FITS file that is located on the legacy machine. These files can only be opened with 'readonly' file access.

• FITS files on stdin or stdout file streams

  If the name of the file to be opened is 'stdin' or '-' (a single dash character) then CFITSIO will read the file from the standard input stream. Similarly, if the output file name is 'stdout' or '-', then the file will be written to the standard output stream. In addition, if the output filename is 'stdout.gz' or '-.gz' then it will be gzip compressed before being written to stdout. This mechanism can be used to pipe FITS files from one task to another without having to write an intermediary FITS file on magnetic disk.

• FITS files that exist only in memory, or shared memory.

  In some applications, such as real time data acquisition, you may want to have one process write a FITS file into a certain section of computer memory, and then be able to open that file in memory with another process. There is a specialized CFITSIO open routine called fits_open_memfile that can be used for this purpose. See the ``CFITSIO User's Reference Guide'' for more details.

• IRAF format images (with .imh file extensions)

  CFITSIO supports reading IRAF format images by converting them on the fly into FITS images in memory. The application program then reads this virtual FITS format image in memory. There is currently no support for writing IRAF format images, or for reading or writing IRAF tables.

• Image arrays in raw binary format

  If the input file is a raw binary data array, then CFITSIO will convert it on the fly into a virtual FITS image with the basic set of required header keywords before it is opened by the application program. In this case the data type and dimensions of the image must be specified in square brackets following the filename (e.g. rawfile.dat[ib512,512]). The first character inside the brackets defines the datatype of the array:

       b         8-bit unsigned byte
       i        16-bit signed integer
       u        16-bit unsigned integer
       j        32-bit signed integer
       r or f   32-bit floating point
       d        64-bit floating point
  

  An optional second character specifies the byte order of the array values: b or B indicates big endian (as in FITS files and the native format of SUN UNIX workstations and Mac PCs) and l or L indicates little endian (native format of DEC OSF workstations and IBM PCs). If this character is omitted then the array is assumed to have the native byte order of the local machine. These datatype characters are then followed by a series of one or more integer values separated by commas which define the size of each dimension of the raw array. Arrays with up to 5 dimensions are currently supported.

  Finally, a byte offset to the position of the first pixel in the data file may be specified by separating it with a ':' from the last dimension value. If omitted, it is assumed that the offset = 0. This parameter may be used to skip over any header information in the file that precedes the binary data. Further examples:

    raw.dat[b10000]          1-dimensional 10000 pixel byte array
    raw.dat[rb400,400,12]    3-dimensional floating point big-endian array
    img.fits[ib512,512:2880] reads the 512 x 512 short integer array in a
                             FITS file, skipping over the 2880 byte header