Read

Read bytes of data from a file

Data can be copied using a combination of Read() and Write(). Read() reads bytes of information from an opened file (represented here by the argument 'file') into the buffer given. The argument 'length' is the length of the buffer given.

The value returned is the length of the information actually read. So, when 'actualLength' is greater than zero, the value of 'actualLength' is the number of characters read. Usually, Read() will try to fill up your buffer before returning. A value of zero means that end-of-file has been reached. Errors are indicated by a value of -1.

Note:

this is an unbuffered operation, i.e. the request is passed

directly to the file system. Buffered I/O is more efficient for small reads and writes; see FGetC().

Read/write access to the contents of files may be restricted through the use of advisory record locking via LockRecord(), LockRecords(), etc.

file

BCPL pointer to a FileHandle

buffer

pointer to buffer

length

integer; this should always be a number > zero. While a length of zero is a valid choice, the Read() return value zero may be ambiguous, suggesting that the end of the file has been reached.

actualLength

integer. A value of zero indicates that the end of the file has been reached and no further data is available for reading. A value of -1 indicates an error; call IoErr() to find out why Read() has failed. Any value > zero indicates success, this being the number of bytes which have been transferred from the file into the buffer provided.

Amiga file system operations limit the size of files to 2 GBytes (2,147,483,647 bytes). It is safe to assume that random access to files which do not exceed this limitation is reliable, unless the file system itself imposes additional size limitations. File systems may even make larger files accessible, but you may find that random access becomes unreliable. Reading data sequentially beyond the 2 GByte limit may become unreliable, too.

Reading from a read-protected file may be denied by the file system, regardless of whether it was opened with the MODE_NEWFILE, MODE_OLDFILE and MODE_READWRITE access modes. Prior to the introduction of the FastFileSystem (V34), the Amiga ROM file system ignored the file read protection if Read() was used.

Open(), Close(), Write(), Seek(), FGetC(), FRead(), IoErr(), LockRecord(), LockRecords()