Name

NFSPROC3_READDIRPLUS - Extended Read From Directory

Call Arguments

 

struct READDIRPLUS3args {
    nfs_fh3 dir;
    cookie3 cookie;
    cookieverf3 cookieverf;
    count3 dircount;
    count3 maxcount;
};

Return Arguments

 

struct entryplus3 {
    fileid3 fileid;
    filename3 name;
    cookie3 cookie;
    post_op_attr name_attributes;
    post_op_fh3 name_handle;
    entryplus3 *nextentry;
};

struct dirlistplus3 {
    entryplus3 *entries;
    bool eof;
};

struct READDIRPLUS3resok {
    post_op_attr dir_attributes;
    cookieverf3 cookieverf;
    dirlistplus3 reply;
};

struct READDIRPLUS3resfail {
    post_op_attr dir_attributes;
};

union READDIRPLUS3res switch (nfsstat3 status) {
    case NFS3_OK:
        READDIRPLUS3resok resok;
    default:
        READDIRPLUS3resfail resfail;
};

RPC Procedure Description

 

READDIRPLUS3res
NFSPROC3_READDIRPLUS(READDIRPLUS3args) = 17;

Description

Procedure READDIRPLUS retrieves a variable number of entries from a file system directory and returns complete information about each along with information to allow the client to request additional directory entries in a subsequent READDIRPLUS. READDIRPLUS differs from READDIR only in the amount of information returned for each entry. In READDIR, each entry returns the filename and the fileid. In READDIRPLUS, each entry returns the name, the fileid, attributes (including the fileid) and file handle.

On entry, the arguments in READDIRPLUS3args are:

dir

The file handle for the directory to be read.

cookie

An opaque value identifying a point in a directory The client sets it to zero in the first request to read the directory. On subsequent requests, it should be a cookie as returned by the server.

cookieverf

An opaque value verifying the value of the cookie. The client sets it to zero in the first request to read the directory. On subsequent requests, it should be a cookieverf, as returned by the server. The cookieverf must match that returned by the READDIRPLUS call in which the cookie was acquired.

dircount

The maximum number of bytes of directory information to be returned. This number does not include the size of the attributes and file handle portions of the result.

maxcount

The maximum size of the READDIRPLUS3resok structure, in bytes. The size must include all XDR overhead. The server may return fewer than maxcount bytes of data.

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

dir_attributes

The attributes of the directory dir.

cookieverf

The cookie verifier.

reply

The directory list:

entries

Zero or more directory (.IR entryplus3 ) entries.

eof

TRUE if the last member of reply.entries is the last entry in the directory or the list reply.entries is empty and the cookie corresponded to the end of the directory. If FALSE, there may be more entries to read.

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

dir_attributes

The attributes of the directory dir.

Implementation Guidance

Issues that need to be understood for this procedure include increased cache flushing activity on the client (as new file handles are returned with names that are entered into caches) and over-the-wire overhead versus expected subsequent LOOKUP elimination. This procedure may improve performance for directory browsing where attributes are always required (such as for the Apple Macintosh operating system and for MS-DOS).

The dircount and maxcount fields are included as an optimisation. Consider a READDIRPLUS call on a UNIX operating system implementation for 1048 bytes; the reply does not contain many entries because of the overhead due to attributes and file handles. An alternative is to issue a READDIRPLUS call for 8192 bytes and then only use the first 1048 bytes of directory information. However, the server doesn't know that all that is needed is 1048 bytes of directory information (as would be returned by READDIR). It sees the 8192 byte request and issues a VOP_READDIR for 8192 bytes. It then steps through all of those directory entries, obtaining attributes and file handles for each entry. When it encodes the result, the server only encodes until it gets 8192 bytes of results, which include the attributes and file handles. Thus, it has done a larger VOP_READDIR and many more attribute fetches than it needed to. The ratio of the directory entry size to the size of the attributes plus the size of the file handle is usually at least 8 to 1. The server has done much more work than it needed to.

The solution to this problem is for the client to provide two counts to the server. The first is the number of bytes of directory information that the client really wants, dircount. The second is the maximum number of bytes in the result, including the attributes and file handles, maxcount. Thus, the server will issue a VOP_READDIR for only the number of bytes that the client really wants to get, not an inflated number. This should help to reduce the size of VOP_READDIR requests on the server, thus reducing the amount of work done there, and to reduce the number of VOP_LOOKUP, VOP_GETATTR and other calls done by the server to construct attributes and file handles.

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_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_NOTDIR

Not a directory. The caller specified a non-directory in a directory operation.

NFS3ERR_BAD_COOKIE

A READDIR or READDIRPLUS cookie is stale.

NFS3ERR_TOOSMALL

The buffer or request is too small.

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_NOTSUPP

The operation is not supported.

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.