Name

NFSPROC3_READ - Read From File

Call Arguments

 

struct READ3args {
    nfs_fh3 file;
    offset3 offset;
    count3 count;
};

Return Arguments

 

struct READ3resok {
    post_op_attr file_attributes;
    count3 count;
    bool eof;
    opaque data<>;
};

struct READ3resfail {
    post_op_attr file_attributes;
};

union READ3res switch (nfsstat3 status) {
    case NFS3_OK:
        READ3resok resok;
    default:
        READ3resfail resfail;
};

RPC Procedure Description

 

READ3res
NFSPROC3_READ(READ3args) = 6;

Description

Procedure READ reads data from a file.

On entry, the arguments in READ3args are:

file

The file handle of the file from which data is to be read. This must identify a file system object of type NF3REG.

offset

The position within the file at which the read is to begin. An offset of zero means to read data starting at the beginning of the file. If offset is greater than or equal to the size of the file, the status NFS3_OK is returned with count set to zero and eof set to TRUE, subject to access permission checking.

count

The number of bytes of data that are to be read. If count is zero, the READ will succeed and return zero bytes of data, subject to access permission checking. The count must be less than or equal to the value of the rtmax field in the FSINFO reply structure for the file system that contains file. If greater, the server may return only rtmax bytes, resulting in a short read.

Upon successful return, READ3res.status is NFS3_OK and READ3res.resok contains:

file_attributes

The attributes of the file on completion of the read.

count

The number of bytes of data returned by the read.

eof

If the read ended at the end-of-file (formally, in a correctly formed READ request, if READ3args.offset plus READ3resok.count is equal to the size of the file), eof is returned as TRUE ; otherwise it is FALSE. A successful READ of an empty file will always return eof as TRUE.

data

The counted data read from the file.

Otherwise, READ3res.status contains the error on failure and READ3res.resfail contains the following:

file_attributes

The post-operation attributes of the file.

Implementation Guidance

The nfsdata type used for the READ and WRITE operations in the NFS Version 2 protocol defining the data portion of a request or reply has been changed to a variable-length opaque byte array. The maximum size allowed by the protocol is now limited by what XDR and underlying transports will allow. There are no artificial limits imposed by the NFS Version 3 protocol. Consult the FSINFO procedure description for details.

It is possible for the server to return fewer than count bytes of data. If the server returns less than the count requested and eof set to FALSE, the client should issue another READ to get the remaining data. A server may return less data than requested under several circumstances. The file may have been truncated by another client or perhaps on the server itself, changing the file size from what the requesting client believes to be the case. This would reduce the actual amount of data available to the client. It is possible that the server may back off the transfer size and reduce the read request return. Server resource exhaustion may also occur, necessitating a smaller read return.

Some NFS Version 2 protocol client implementations chose to interpret a short read response as indicating end-of-file. The addition of the eof flag in the NFS Version 3 protocol provides a correct way of handling end-of-file.

Some NFS Version 2 protocol server implementations incorrectly returned NFSERR_ISDIR if the file system object type was not a regular file. The correct return value for the NFS Version 3 protocol is NFS3ERR_INVAL.

Return Codes

NFS3ERR_IO

I/O error. Some sort of hard error occurred when the operation was in progress. This could be a disk error, for example.

NFS3ERR_NXIO

No such device or address.

NFS3ERR_ACCES

Permission denied. The caller does not have the correct permission to perform the requested operation. Contrast this with NFS3ERR_PERM, which restricts itself to owner permission failures.

NFS3ERR_INVAL

Invalid argument or unsupported argument for an operation. Two examples are attempting a READLINK on an object other than a symbolic link or attempting to SETATTR a time field on a server that does not support this operation.

NFS3ERR_STALE

Invalid file handle. The file handle given in the arguments was invalid. The file referred to by that file handle no longer exists or access to it has been revoked.

NFS3ERR_BADHANDLE

Invalid NFS file handle. The file handle failed internal consistency checks.

NFS3ERR_SERVERFAULT

An error occurred on the server, which does not map to any of the valid NFS Version 3 protocol error values. The client should translate this into an appropriate error. Clients based on an XPG system may choose to translate this to EIO.