int fits_open_file(fitsfile **fptr, char *filename, int mode, int *status) int fits_create_file(fitsfile **fptr, char *filename, int *status) int fits_close_file(fitsfile *fptr, int *status)
These routines open or close a file. The first fitsfile parameter in these and nearly every other CFITSIO routine is a pointer to a structure that CFITSIO uses to store relevant parameters about each opened file. You should never directly read or write any information in this structure. Memory for this structure is allocated automatically when the file is opened or created, and is freed when the file is closed.
The mode parameter in fits_open_file can be set to either READONLY or READWRITE to select the type of file access that will be allowed. These symbolic constants are defined in fitsio.h.
In fits_create_file, the filename is simply the root name of
the file to be created. You can overwrite an existing file by
prefixing the name with a `!' character (on the Unix command line this
must be prefixed with a backslash, as in `\!file.fit'
). If the
filename is stdout or "-" (a single dash character)
then the output file will be piped to the stdout stream. You can
chain several tasks together by writing the output from the first task
to stdout and then reading the input file in the 2nd task from
stdin.
When opening an existing file with fits_open_file, the filename can include optional arguments, enclosed in square brackets, giving the name or index number of a particular HDU to be opened, and/or other filtering operations that should be applied to the input file. See section 6 for more examples of these powerful filtering capabilities. Here are some examples:
myfile.fit[EVENTS] - opens the file then moves to the EVENTS extension. myfile.fit[3] - opens the 3rd extension in the file myfile.fit[3][counts > 0] - opens the table in the 3rd extension and creates a virtual table by selects only those rows where the COUNTS column value is greater than 0.