Connected: An Internet Encyclopedia
RFC 1813 - 3.3.6 Procedure 6: READ - Read From file

Top: Connected: An Internet Encyclopedia
Up: Requests For Comments
Up: RFC 1813
Up: 3. Server Procedures
Up: 3.3. Procedure Descriptions
Prev: 3.3.5 Procedure 5: READLINK - Read from symbolic link
Next: 3.3.7 Procedure 7: WRITE - Write to file

### 3.3.6 Procedure 6: READ - Read From file

SYNOPSIS

            READ3res NFSPROC3_READ(READ3args) = 6;

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

            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;
            };

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 0 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 0 and eof set to TRUE, subject to access permissions checking.

  count

    The number of bytes of data that are to be read. If count is 0, the READ will succeed and return 0 bytes of data, subject to access permissions checking. 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.

  On 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

  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 EOF. The addition of the eof flag in the NFS version 3 protocol provides a correct way of handling EOF.

  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.

ERRORS

  NFS3ERR_IO NFS3ERR_NXIO NFS3ERR_ACCES NFS3ERR_INVAL NFS3ERR_STALE NFS3ERR_BADHANDLE NFS3ERR_SERVERFAULT

  SEE ALSO READLINK.

Next: 3.3.7 Procedure 7: WRITE - Write to file

Connected: An Internet Encyclopedia
RFC 1813 - 3.3.6 Procedure 6: READ - Read From file