- NAME
- file_exists - CHECK A FILE EXISTS

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INPUT

- RETURN

- clnopen - OPEN FILE WITH ERROR CHECKING

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INPUT

- RETURN

- clnclose - CLOSE FILE WITH ERROR CHECKING

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INPUT
- INOUT

- RETURN

- clnremove - DELETE FILE WITH ERROR CHECKING

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INPUT

- RETURN
- BUGS

- f2str - READ FILE INTO STRING

- SYNOPSIS
- DESCRIPTION
- PARAMETERS

- INOUT

- RETURN
- BUGS

# NAME

fops.c - file operations

Version Tag $Id: fops.c,v 1.17 2006/02/06 19:55:46 db60 Exp $

# file_exists - CHECK A FILE EXISTS

## SYNOPSIS

        Lvb_bool file_exists(const char *const nam);

## DESCRIPTION

Checks whether a file may be opened for reading. This actually tests both the presence of the file and its permissions.

## PARAMETERS

### INPUT

nam

  Pointer to first byte of a string giving the name of the file to check.

## RETURN

Returns LVB_TRUE if the file exists and may be opened for reading, LVB_FALSE otherwise.

# clnopen - OPEN FILE WITH ERROR CHECKING

## SYNOPSIS

        FILE *clnopen(const char *const nam, const char *const mod);

## DESCRIPTION

Open a file, or crash verbosely on failure.

## PARAMETERS

### INPUT

nam

  Pointer to first byte of a string giving the name of the file to open.

mod

  Mode to open the file with. Values are as for the standard C library function `fopen`.

## RETURN

Returns a pointer to the newly opened file structure.

# clnclose - CLOSE FILE WITH ERROR CHECKING

## SYNOPSIS

        void clnclose(FILE *const fp, const char *const fnam);

## DESCRIPTION

Close a file, crashing verbosely on file error or failure. Or, if passed a NULL file pointer, do nothing.

## PARAMETERS

### INPUT

fnam

  Pointer to first byte of a string giving the name of the file to close.

### INOUT

fp

  Pointer to the file to check for errors and close, or NULL.

## RETURN

Returns a pointer to the newly opened file structure.

# clnremove - DELETE FILE WITH ERROR CHECKING

## SYNOPSIS

        void clnremove(const char *const fnam);

## DESCRIPTION

Delete a file, logging a strong warning on failure.

## PARAMETERS

### INPUT

fnam

  Pointer to first byte of a string giving the name of the file to delete.

## RETURN

None.

## BUGS

For portability, the file should not be open on calling `clnremove`.

# f2str - READ FILE INTO STRING

## SYNOPSIS

        char *f2str(FILE *const stream);

## DESCRIPTION

Read contents of a file into a new string. The text read is terminated by newline if not already present, and finally by '\0'. The file is treated as text. One may deallocate memory for the new string using the standard library function `free`.

## PARAMETERS

### INOUT

stream

  Pointer to file, which must be open in a readable mode and positioned at the start.

## RETURN

Pointer to first byte in string containing the contents of the file when read as text.

## BUGS

Does not know how to interpret newlines if the file has a different representation of newline to that used by the current system.

Will not work correctly if the file size alters during the call to `f2str`.

Does not work correctly if the stream is positioned anywhere other than at the start of the file on calling `f2str`.