(v13) read_file read data from a file on the device

This page applies to Harlequin v13.1r0 and later; and to Harlequin Core but not Harlequin MultiRIP

TEXT

  int32 read_file ( DEVICELIST *dev,
  DEVICE_FILEDESCRIPTOR descriptor,
  uint8 *buff,
  int32 len );

The descriptor will be one returned by a previous open_file on this device. The bytes read should be stored in ascending addresses starting at buff . Unless the device type specifies an explicit size (as described in (v13) device_buffersize determine file buffer size the space available in buff (len) is guaranteed to be at least 1024 bytes, although the read routine can return fewer if appropriate.

The routine should return the number of bytes added to the buffer, or -1 if some error occurred. Returning 0 (zero) indicates that the end of file has been reached.

If an error occurs, the Harlequin Core will not assume anything about the contents of the buffer. Thus, it is safe to put bytes into this buffer even if an error occurs at some point before all the bytes have been read.

If an error occurs during the read, the routine should return -1 and last_error should return DeviceIOError .

Note that some implementations may need to close the file if the file is deleted (see delete_file ) and so an error may need to be returned even if there is no error in the underlying file system.

As an example, this behavior matches the usual behavior of UNIX file descriptors and so, except for the need not to block for any long period of time, both the file system and socket devices could just pass descriptor , buff , and len to the UNIX read system call. last_error would examine errno to determine the error to return.