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.