4.5 Dealing with Character Strings

The character string values in a FITS header or in an ASCII column in a FITS table extension are generally padded out with non-significant space characters (ASCII 32) to fill up the header record or the column width. When reading a FITS string value, the CFITSIO routines will strip off these non-significant trailing spaces and will return a null-terminated string value containing only the significant characters. Leading spaces in a FITS string are considered significant. If the string contains all blanks, then CFITSIO will return a single blank character, i.e, the first blank is considered to be significant, since it distinguishes the string from a null or undefined string, but the remaining trailing spaces are not significant.

Similarly, when writing string values to a FITS file the CFITSIO routines expect to get a null-terminated string as input; CFITSIO will pad the string with blanks if necessary when writing it to the FITS file.

The FITS standard does not require trailing spaces to be treated in this way, but it does allow a more seamless transition from the FORTRAN FITS world where trailing spaces are often treated as insignificant. Users who wish the greatest fidelity when transferring strings can use the _byt variants of column readers and writers (functions fits_{read,write}_col_byt). These routines will transfer the raw fixed-length vectors of character bytes of the column, including any trailing blanks of course. The _byt variants make no attempt to null-terminate any elements. A NULL string would be indicated by its first character being a NUL byte.

When calling CFITSIO routines that return a character string it is vital that the size of the char array be large enough to hold the entire string of characters, otherwise CFITSIO will overwrite whatever memory locations follow the char array, possibly causing the program to execute incorrectly. This type of error can be difficult to debug, so programmers should always ensure that the char arrays are allocated enough space to hold the longest possible string, including the terminating NULL character. The fitsio.h file contains the following defined constants which programmers are strongly encouraged to use whenever they are allocating space for char arrays:

#define FLEN_FILENAME 1025 /* max length of a filename */
#define FLEN_KEYWORD   72  /* max length of a keyword  */
#define FLEN_CARD      81  /* length of a FITS header card */
#define FLEN_VALUE     71  /* max length of a keyword value string */
#define FLEN_COMMENT   73  /* max length of a keyword comment string */
#define FLEN_ERRMSG    81  /* max length of a CFITSIO error message */
#define FLEN_STATUS    31  /* max length of a CFITSIO status text string */

For example, when declaring a char array to hold the value string of FITS keyword, use the following statement:

    char value[FLEN_VALUE];

Note that FLEN_KEYWORD is longer than needed for the nominal 8-character keyword name because the HIERARCH convention supports longer keyword names.