ReadFile

int ReadFile (int fileHandle, char buffer[], int count);

Purpose

Reads up to count bytes of data from a file or the Standard Input into buffer. Reading starts at the current position of the file pointer. When ReadFile completes, the file pointer points to the next unread character in the file.

The return value can be less than the number of bytes requested if ReadFile reaches the end of the file before the byte count is satisfied. If you open the file in ASCII mode, ReadFile counts each carriage return/linefeed (CR/LF) combination read as one character because the pair is translated into an LF when ReadFile stores it in the buffer.

Note  ReadFile does not terminate the buffer with an ASCII NUL.
Caution  The Windows SDK also contains a ReadFile function. If you include windows.h and do not include formatio.h, you will get compile errors if you call ReadFile.

Parameters

Input
Name Type Description
fileHandle integer The file from which to read the data. Call OpenFile to obtain a fileHandle. To read from the Standard I/O window, pass 0 for fileHandle.
count integer Maximum number of bytes to read. count must not be greater than buffer size.
Output
Name Type Description
buffer string Buffer into which you read data. You must allocate space for this buffer before you call ReadFile.

Return Value

Name Type Description
n integer Number of bytes read.

A value of –1 indicates that an error occurred during the read operation, possibly because of a bad file handle. You can use GetFmtIOError to get more information about the type of error that occurred.

A return value of 0 indicates that ReadFile did not read any bytes because it reached the end of the file.

Note  If you opened the file in ASCII mode, the number of bytes returned does NOT include the CR in a CR/LF combination because each CR/LF combination is translated to an LF when the data is read.