Previous section.

Protocols for Interworking: XNFS, Version 3W
Copyright © 1998 The Open Group


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



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:

The file handle for the directory to be read.

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.

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.

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:

The attributes of the directory dir.

The cookie verifier.

The directory list:

Zero or more directory (.IR entry3 ) entries.

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:

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

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

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.

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


A READDIR or READDIRPLUS cookie is stale.


The buffer or request is too small.

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.


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


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.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index