General File IO

Although one may use the standard UNIX file interface (fprintf, for example), the BIC Volume IO Library contains a set of routines for doing all file operations, with the potential to be portable to other operating systems. There are some other minor advantages, including the automatic expansion of ~ and environment variables. Also, automatic decompression of compressed files is provided.

public  void  expand_filename(
    char  filename[],
    char  expanded_filename[] )

Searches the argument filename for certain patterns, and expands them appropriately, storing the resulting expanded filename in the second argument, expanded_filename, which must be a different string pointer. Any sequence of characters starting with a ~ up to but not including a slash, /, will be changed to the specified users home directory. Any occurrence of a dollar sign, $, will result in the following text, up to the next slash, being expanded to the environment variable specified by the text. This expansion can be avoided by placing a backslash, , before any ~ or $. In all the following functions which take filenames, automatic expansion of filenames is performed.

public  BOOLEAN  filename_extension_matches(
    char   filename[],
    char   extension[] )

Returns TRUE if the file ends in the given extension, preceded by a period. e.g., filename_extension_matches( "volume.mnc" , "mnc" ) returns TRUE. Correctly handles compressed files, e.g., passing the arguments, "volume.mnc.Z" and "mnc" returns TRUE.

public  void  remove_directories_from_filename(
    char  filename[],
    char  filename_no_directories[] )

Strips the directories from the filename, placing the result in the second argument, filename_no_directories.

public  void  extract_directory(
    char    filename[],
    char    directory[] )

Extracts the directory from the filename, placing the result in the second argument, directory.

public  void  get_absolute_filename(
    char    filename[],
    char    directory[],
    char    abs_filename[] )

Given a filename and a current directory, constructs an absolute filename (one starting with a slash, /.

public  BOOLEAN  file_exists(
    char        filename[] )

Returns TRUE if the file exists, FALSE otherwise.

public  void  remove_file(
    char  filename[] )

Removes the specified file.

public  void  unlink_file(
    char        filename[] )

Unlinks the specified file, which results in the file being removed only after all other references to it are closed.

public  Status  open_file(
    char               filename[],
    IO_types           io_type,
    File_formats       file_format,
    FILE               **file )
public  Status  open_file_with_default_suffix(
    char               filename[],
    char               default_suffix[],
    IO_types           io_type,
    File_formats       file_format,
    FILE               **file )

The function open_file() opens the specified file, where io_type must be one of WRITE_FILE or READ_FILE, and file_format must be one of ASCII_FORMAT or BINARY_FORMAT. If successful, the file pointer is passed back in the last argument and a status of OK is returned. Otherwise, a null pointer is passed back, and a status of ERROR is returned. Filename expansion is automatically performed. The second function performs the same task as open_file with the addition that it automatically adds the specified suffix extension, if needed. On input, if the specified file does not exist and the file does not have an extension, then it looks for the specified file with the default extension.

public  Status  close_file(
    FILE     *file )

Closes the file, returning OK if successful.

public  Status  set_file_position(
    FILE     *file,
    long     byte_position )

Seeks to the specified position in the file, where 0 corresponds to the beginning of the file, returning OK if successful.

public  Status  flush_file(
    FILE     *file )

Flushes the file buffer of any pending output, returning OK if successful.

public  Status  input_character(
    FILE  *file,
    char   *ch )

Inputs a character from the file and passes it back as the second argument. If the character is the end of file character, returns a status of ERROR, otherwise, OK.

public  Status  unget_character(
    FILE  *file,
    char  ch )

Places the character back on the input queue.

public  Status  input_nonwhite_character(
    FILE   *file,
    char   *ch )

Inputs the next non-white character, i.e. the next character that is neither a blank, a tab, or a newline character.

public  Status   skip_input_until(
    FILE   *file,
    char   search_char )

Inputs characters from the file until the specified search character is found.

public  Status  input_string(
    FILE  *file,
    char  str[],
    int   string_length,
    char  termination_char )

Inputs a string from the file, where the maximum storage of the string is specified by the argument string_length. The file is read into the string until either the termination character or a newline character is found. If the string ends at a newline character and the termination character is not a newline, the next character available from the file will be the newline character. Otherwise, the next character available is the one just after the termination character found.

public  Status  input_quoted_string(
    FILE            *file,
    char            str[],
    int             str_length )

Inputs a string from a file, delimited by quotation marks, returning OK or ERROR. The maximum storage available in the str pointer is specified by the third argument, str_length. After successful reading of a string, the next character available from the file is the one just after the ending quotation mark.

public  Status  input_line(
    FILE    *file,
    char    line[],
    int     str_length )

Inputs characters from the file into the argument line, up until the next newline character, or until str_length characters have been read. If a newline was found, the next available character will be the one after the newline. The newline character is not stored in the string.

public  Status  input_boolean(
    FILE            *file,
    BOOLEAN         *b )

Inputs the next non-white character. If it is a ``f'' or ``F'', then the value FALSE is passed back. If it is a ``t'' or ``T'', then the value TRUE is passed back. Otherwise ERROR is returned.

public  Status  input_short(
    FILE            *file,
    short           *s )
public  Status  input_unsigned_short(
    FILE            *file,
    unsigned short  *s )
public  Status  input_int(
    FILE            *file,
    int             *i )
public  Status  input_real(
    FILE            *file,
    Real            *r )
public  Status  input_float(
    FILE            *file,
    float           *f )
public  Status  input_double(
    FILE            *file,
    double          *d )

Inputs a value of the specified type from an ascii file.

public  Status  input_newline(
    FILE            *file )

Inputs and discards characters from the file up to and including the next newline character. Returns OK if a newline was found, or ERROR if the end of file was reached first.

public  Status  input_binary_data(
    FILE            *file,
    void            *data,
    size_t          element_size,
    int             n )

Inputs an array of data from a file, in binary format. The array contains n elements, each of size element_size. Returns either OK or ERROR.

public  Status  output_character(
    FILE   *file,
    char   ch )

Outputs a character to the file, returning OK or ERROR.

public  Status  output_string(
    FILE  *file,
    char  str[] )

Outputs the specified string to the file, returning OK or ERROR.

public  Status  output_quoted_string(
    FILE            *file,
    char            str[] )

Outputs a quotation mark, the specified string, and a closing quotation mark.

public  Status  output_newline(
    FILE            *file )

Outputs a newline character, returning OK or ERROR.

public  Status  output_boolean(
    FILE            *file,
    BOOLEAN         b )

If the argument is TRUE, then a space and the letter ``T'' is output, otherwise, a space and the letter ``F'' is output.

public  Status  output_short(
    FILE            *file,
    short           s )
public  Status  output_unsigned_short(
    FILE            *file,
    unsigned short  s )
public  Status  output_int(
    FILE            *file,
    int             i )
public  Status  output_real(
    FILE            *file,
    Real            r )
public  Status  output_float(
    FILE            *file,
    float           f )
public  Status  output_double(
    FILE            *file,
    double          d )

Outputs a space and then the specified value to an ascii file.

public  Status  output_binary_data(
    FILE            *file,
    void            *data,
    size_t          element_size,
    int             n )

Outputs an array of data to a file, in binary format. The array contains n elements, each of size element_size. Returns either OK or ERROR.

public  Status  io_binary_data(
    FILE            *file,
    IO_types        io_flag,
    void            *data,
    size_t          element_size,
    int             n )

Inputs or outputs the specified binary data, depending on whether the argument io_flag is READ_FILE or WRITE_FILE.

public  Status  io_newline(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format )

Inputs or outputs an ascii newline character, depending on whether the argument io_flag is READ_FILE or WRITE_FILE. If the format argument is BINARY_FORMAT, this function does nothing.

public  Status  io_quoted_string(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    char            str[],
    int             str_length )

If the format argument is ASCII_FORMAT, inputs or outputs a quotation mark delimited string, depending on whether the argument io_flag is READ_FILE or WRITE_FILE. IF the format argument is BINARY_FORMAT, inputs or outputs a string preceded by an integer indicating the length of the string.

public  Status  io_boolean(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    BOOLEAN         *b )
public  Status  io_short(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    short           *short_int )
public  Status  io_unsigned_short(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    unsigned short  *unsigned_short )
public  Status  io_unsigned_char(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    unsigned  char  *c )
public  Status  io_int(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    int             *i )
public  Status  io_real(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    Real            *r )
public  Status  io_float(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    float           *f )
public  Status  io_double(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    double          *d )

Inputs or outputs a binary or ascii value of the specified type.

public  Status  io_ints(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    int             n,
    int             *ints[] )

Inputs or outputs an array of integers in binary or ascii format.

public  Status  io_unsigned_chars(
    FILE            *file,
    IO_types        io_flag,
    File_formats    format,
    int             n,
    unsigned char   *unsigned_chars[] )

Inputs or outputs an array of unsigned characters in binary or ascii format.