Name

NFSPROC3_READDIR - Read From Directory

Call Arguments

 

struct READDIR3args {
    nfs_fh3 dir;
    cookie3 cookie;
    cookieverf3 cookieverf;
    count3 count;
};

Return Arguments

 

struct entry3 {
    fileid3 fileid;
    filename3 name;
    cookie3 cookie;
    entry3 *nextentry;
};

struct dirlist3 {
    entry3 *entries;
    bool eof;
};

struct READDIR3resok {
    post_op_attr dir_attributes;
    cookieverf3 cookieverf;
    dirlist3 reply;
};

struct READDIR3resfail {
    post_op_attr dir_attributes;
};

union READDIR3res switch (nfsstat3 status) {
    case NFS3_OK:
        READDIR3resok resok;
    default:
        READDIR3resfail resfail;
};

RPC Procedure Description

 

READDIR3res
NFSPROC3_READDIR(READDIR3args) = 16;

Description

Procedure READDIR retrieves a variable number of entries, in sequence, from a directory and returns the name and file identifier for each, with information to allow the client to request additional directory entries in a subsequent READDIR request.

On entry, the arguments in READDIR3args 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 READDIR in which the cookie was acquired.

count

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

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

dir_attributes

The attributes of the directory dir.

cookieverf

The cookie verifier.

reply

The directory list:

entries

Zero or more directory (.IR entry3 ) 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, READDIR3res.status contains the error on failure and READDIR3res.resfail contains the following:

dir_attributes

The attributes of the directory dir.

Implementation Guidance

In the NFS Version 2 protocol, each directory entry returned included a cookie identifying a point in the directory. By including this cookie in a subsequent READDIR, the client could resume the directory read at any point in the directory. One problem with this scheme was that there was no easy way for a server to verify that a cookie was valid. If two READDIRs were separated by one or more operations that changed the directory in some way (for example, reordering or compressing it), it was possible that the second READDIR could miss entries, or process entries more than once. If the cookie was no longer usable, for example, pointing into the middle of a directory entry, the server would have to either round the cookie down to the cookie of the previous entry or round it up to the cookie of the next entry in the directory. Either way would possibly lead to incorrect results and the client would be unaware that any problem existed.

In the NFS Version 3 protocol, each READDIR request includes both a cookie and a cookie verifier. For the first call, both are set to zero. The response includes a new cookie verifier, with a cookie per entry. For subsequent READDIRs, the client must present both the cookie and the corresponding cookie verifier. If the server detects that the cookie is no longer valid, the server will reject the READDIR request with the status NFS3ERR_BAD_COOKIE. The client should be careful to avoid holding directory entry cookies across operations that modify the directory contents, such as REMOVE and CREATE.

One implementation of the cookie-verifier mechanism might be for the server to use the modification time of the directory, but this might be overly restrictive. A better approach would be to record the time of the last directory modification that changed the directory organisation in a way that would make it impossible to interpret a cookie reliably. Servers in which directory cookies are always valid are free to use zero as the verifier always.

The server may return fewer than count bytes of XDR-encoded entries. The count specified by the client in the request should be greater than or equal to FSINFO dtpref.

Since UNIX clients give a special meaning to the fileid value zero, UNIX clients should be careful to map zero fileid values to some other value and servers should try to avoid sending a zero fileid.

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