NXRead

Atomically positions a file pointer and reads from a specified file.

Library:LibC
Classification:NKS
Service:File and Directory I/O

Syntax

  #include <nks/fsio.h> 
  
  int NXRead (
     NXHandle_t      handle, 
     NXOffset_t      offset, 
     size_t          length, 
     void           *address,
     unsigned long   flags, 
     size_t         *bytesRead);

Parameters

handle

(IN) Specifies a file handle (or descriptor), which refers to a system-maintained state description for a file. If a FIFO or other sequential I/O device, all values that might be in offset are ignored.

offset

(IN) Specifies the offset at which the read is to start. NXOffset_t is guaranteed to be 64-bits wide.

length

(IN) Specifies the number of bytes to be read. If zero, NXRead returns zero and has no other results.

address

(IN) Points to a memory address (which is meaningful in your virtual machine) where the data read from the file should be placed.

flags

(IN) Pass 0.

bytesRead

(OUT) Points to the number of bytes actually read. This number might be less than length if the number of bytes left in the file is less than length. A value of zero is returned when an end-of-file has been reached. If an error occurs, returns -1.

On a non-blocking FIFO, the number of bytes read may be different than the number requested. In this case, no error is returned, but bytesRead does indicate the number of valid bytes in the buffer.

Return Values

If successful, returns 0. Otherwise, returns one of the following error codes.

Decimal

Hex

Constant

Description

4

0x04

NX_EBADF

handle is not a valid file descriptor open for reading.

9

0x09

NX_EINVAL

offset is greater than the file's size or is less than 0.

24

0x18

NX_EAGAIN

Resource exhaustion prevents successful completion of the call at this time.

28

0x1C

NX_EIO

A physical I/O error has occurred. This can indicate either a failure to read from a local volume or failure of connection to a remote file volume link.

105

0x69

NX_ENOCONTEXT

The calling thread has no NKS context.

Remarks

NXRead attempts to read the number of specified bytes from the file associated with handle into the buffer specified by address.

NXRead reads data previously written to a file. If any portion of a file has not been written, NXRead returns data read from that portion as zero bytes. NXRead cannot be used to read data when the offset parameter is positioned beyond the end-of-file.

NXRead updates the time of last access of the file.

See Also