Subject: READDIR (maxcount as hard limit)

From: Spencer Shepler <[email-masked]>
Date: Fri, 05 Nov 1999 13:29:32 -0600

I have updated the READDIR definition so that maxcount is now a hard
limit and have added the new error to handle the case where maxcount
is not large enough for a single entry.

------
12.2.22.  Operation 23: READDIR - Read Directory

   SYNOPSIS
      (cfh), cookie, cookieverf, dircount, maxcount, attrbits ->
      cookieverf { cookie, filename, attrbits, attributes }

   ARGUMENT

     struct READDIR4args {
             /* CURRENT_FH: directory */
             nfs_cookie4     cookie;
             cookieverf4     cookieverf;
             count4          dircount;
             count4          maxcount;
             bitmap4         attr_request;

     };

   RESULT

     struct entry4 {
             nfs_cookie4     cookie;
             component4      name;
             fattr4          attrs;
             entry4          *nextentry;
     };

     struct dirlist4 {
             entry4          *entries;
             bool            eof;
     };

     struct READDIR4resok {
             cookieverf4     cookieverf;
             dirlist4        reply;
     };

     union READDIR4res switch (nfsstat4 status) {
      case NFS4_OK:
              READDIR4resok  resok4;
      default:
              void;
     };

   DESCRIPTION

     The READDIR procedure retrieves a variable number of entries from a
     file system directory and returns client requested attributes for
     each entry along with information to allow the client to request
     additional directory entries in a subsequent READDIR.

     The arguments contain a cookie value that represents where the
     READDIR should start within the directory.  A value of 0 (zero) for
     the cookie is used to start reading at the beginning of the
     directory.  For subsequent READDIR requests, the client specifies a
     cookie value that is provided by the server on a previous READDIR
     request.

     The cookieverf value should be set to 0 (zero) when the cookie
     value is 0 (zero) (first directory read).  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 dircount portion of the argument is a hint of the maximum
     number of bytes of directory information that should be returned.
     This value is the XDR encoded length of the name of the directory
     entries and the cookie value for the entries.  The server may
     return less data.

     The maxcount value of the argument is the maximum number of bytes
     for the result.  This maximum size represents all of the data being
     returned and includes the XDR overhead.  The server may return less
     data.  If the server is unable to return a single directory entry
     within the maxcount limit, the error NFS4ERR_READDIR_NOSPC will be
     returned to the client.

     Finally, attrbits represents the list of attributes to be returned
     for each directory entry supplied by the server.

     On successful return, the server's response will provide a list of
     directory entries.  Each of these entries contains the name of the
     directory entry, a cookie value for that entry, and the associated
     attributes as requested.

     The cookie value is only meaningful to the server and is used as a
     "bookmark" for the directory entry.  As mentioned, this cookie is
     used by the client for subsequent READDIR operations so that it may
     continue reading a directory.  The cookie is similar in concept to
     a READ offset but should not be interpreted as such by the client.
     Ideally, the cookie value should not change if the directory is
     modified.

     In some cases, the server may encounter an error while obtaining
     the attributes for a directory entry.  Instead of returning an
     error for the entire READDIR operation, the server can instead
     return the attribute 'fattr4_rdattr_error'.  With this the server
     is able to communicate the failure to the client and not fail the
     entire operation in the instance of what might be a transient
     failure.  Obviously, the client must request the
     fattr4_rdattr_error attribute for this method to work properly.  If
     the client does not request the attribute, the server has no choice
     but to return failure for the entire READDIR operation.

     For some file system environments, the directory entries "." and
     ".."  have special meaning and in other environments, they may not.
     If the server supports these special entries within a directory,
     they should not be returned to the client as part of the READDIR
     response.  To enable some client environments, the cookie values of
     0, 1, and 2 are to be considered reserved.  For READDIR arguments,
     cookie values of 1 and 2 should not be used and for READDIR results
     cookie values of 0, 1, and 2 should not returned.

   IMPLEMENTATION

     The server's file system directory representations can differ
     greatly.  A client's APIs may also be bound to the local operating
     environment in a way that does not translate well into the NFS
     protocol.  Therefore the use of the dircount and maxcount fields
     are provided to allow the client the ability to provide guidelines
     to the server.  If the client is aggressive about attribute
     collection during a READDIR, the server has an idea of how to limit
     the encoded response.  The dircount field provides a hint on the
     number of entries based solely on the names of the directory
     entries.

     The cookieverf may be used by the server to help manage cookie
     values that may become stale.  It should be a rare occurance that a
     server is unable to continue properly reading a directory with the
     provided cookie/cookieverf pair.  The server should make every
     effort to avoid this condition since the application at the client
     may not be able to properly handle this type of failure.

     The use of the cookieverf will also protect the client from using
     READDIR cookie values that may be stale.  For example, if the file
     system has been migrated, the server may or may not be able to use
     the same cookie values to service READDIR as the previous server
     used.  With the client providing the cookieverf, the server is able
     to provide the appropriate response to the client.  This prevents
     the case where the server may accept a cookie value but the
     underlying directory has changed and the response is invalid from
     the client's context of its previous READDIR.

   ERRORS

     NFS4ERR_IO

     NFS4ERR_ACCES

     NFS4ERR_NOTDIR

     NFS4ERR_INVAL

     NFS4ERR_STALE

     NFS4ERR_BADHANDLE

     NFS4ERR_BAD_COOKIE

     NFS4ERR_TOOSMALL

     NFS4ERR_NOTSUPP

     NFS4ERR_SERVERFAULT

     NFS4ERR_JUKEBOX

     NFS4ERR_FHEXPIRED

     NFS4ERR_WRONGSEC

     NFS4ERR_MOVED

     NFS4ERR_RESOURCE

     NFS4ERR_READDIR_NOSPC