lq-text: LQU_ReadFile

API long LQU_ReadFile (Severity, Name, What, Lines, Flags) int Severity; CONST char *Name; CONST char *What; char ***Lines; int Flags;

Purpose

Reads the file named by the Name argument, and returns a pointer to an array of pointers to the start of each line in the file.

The Flags argument is any combination of flags from <lqutil.h> combined with bitwise or; in practice, however, LQUF_NORMAL is the most frequently used flag, which is a bitwise or of all of the flags described below.

The flags are as follows:

LQUF_IGNBLANKS to throw away blank lines;
LQUF_IGNSPACES to discard leading and trailing spaces;
LQUF_IGNHASH to discard leading comments (# with a hash-sign);
LQUF_IGNALLHASH to discard comments (# with a hash-sign);
LQUF_ESCAPEOK to accept \# and \\ as # and \.

This is the file descriptor version of LQU_fReadFile.

In the event of an error, the given Severity argument is passed to Error, along with the given What argument, which should be a brief English description, perhaps of the order of three words long, of the file.

Returns

the number of lines read, if any. The char ** pointed to by the Lines argument is set to point to an array of strings, each containing one line of text, NUL-terminated with trailing newlines removed. If E_FATAL was given, LQU_fReadFile does not return after an error.

Errors

Generates a Warning or Error of the given Severity if the file can't be opened, and attempts to diagnose the cause.

Example

int numberOfLines; * char **theLines; int i; * * numberOfLines = LQU_fReadFile(E_FATAL, "julian.txt", "Book of Meditations", , LQUF_NORMAL ); * for (i = 0; i < numberOfLines; i++) { printf("Line %d was: %s\n", i, Lines[i]); efree(Lines[i]); } efree((char *) Lines);