Subject: wordsmithing corrections

From: Mike Eisler <[email-masked]>
Date: Fri, 30 Aug 2002 08:14:29 -0700

Wordsmithing changes. With the exception of the correct
error codes for RESTOREFH, these have no impact on the
protocol's semantics or on the wire formats. Most of these
offenses were from yours truly.

CHANGE:

   verifier4     typedef opaque        verifier4[NFS4_VERIFIER_SIZE];
                 Verifier used for various operations (COMMIT, CREATE,
                 OPEN, READDIR, SETCLIENTID, SETCLIENTID_CONFIRM, WRITE)
                 NFS4_VERIFIER_SIZE is defined as 8

TO: (because the other multisentence items have a trailing period)

   verifier4     typedef opaque        verifier4[NFS4_VERIFIER_SIZE];
                 Verifier used for various operations (COMMIT, CREATE,
                 OPEN, READDIR, SETCLIENTID, SETCLIENTID_CONFIRM, WRITE)
                 NFS4_VERIFIER_SIZE is defined as 8.

CHANGE:

   Since transports, including TCP, do not always synchronously inform a
   peer when the other peer has broken the connection (for example, when
   an NFS server reboots), so the NFS version 4 client may want to
   actively "probe" the connection to see if has been broken.  Use of

TO:

   Some reliable transports, such as TCP, do not always synchronously inform a
   peer when the other peer has broken the connection (for example, when
   an NFS server reboots), so the NFS version 4 client may want to
   actively "probe" the connection to see if has been broken.  Use of

CHANGE:

4.2.4.  One Method of Constructing a Volatile Filehandle

   As mentioned, in some instances a filehandle is stale (no longer
   valid; perhaps because the file was removed from the server) or it is
   expired (the underlying file is valid but since the filehandle is
   volatile, it may have expired).  Thus the server needs to be able to
   return NFS4ERR_STALE in the former case and NFS4ERR_FHEXPIRED in the
   latter case. This can be done by careful construction of the volatile
   filehandle.  One possible implementation follows.

   A volatile filehandle, while opaque to the client could contain:

   [volatile bit = 1 | server boot time | slot | generation number]

   o    slot is an index in the server volatile filehandle table

   o    generation number is the generation number for the table
        entry/slot

   If the server boot time is less than the current server boot time,
   return NFS4ERR_FHEXPIRED.  If slot is out of range, return
   NFS4ERR_BADHANDLE.  If the generation number does not match, return
   NFS4ERR_FHEXPIRED.

TO: [ the problem with the above is that it promises an algorithm that
	will produce NFS4ERR_STALE, then goes on to produce one that
	does not. I can't think of an algorithm that will usefully
        produce NFS4ERR_STALE. So I propose removing the reference
        to _STALE]

4.2.4.  One Method of Constructing a Volatile Filehandle

   A volatile filehandle, while opaque to the client could contain:

   [volatile bit = 1 | server boot time | slot | generation number]

   o    slot is an index in the server volatile filehandle table

   o    generation number is the generation number for the table
        entry/slot

   When the client presents a volatile filehandle, the
   server makes the following checks, which assume that the
   check for the volatile bit has passed. If the server
   boot time is less than the current server boot time,
   return NFS4ERR_FHEXPIRED.  If slot is out of range,
   return NFS4ERR_BADHANDLE.  If the generation number
   does not match, return NFS4ERR_FHEXPIRED.

CHANGE:

5.4.  Classification of Attributes

   Each of the Mandatory and Recommended attributes can be classified in
   one of three categories: per server, per filesystem, or per
   filesystem object.  Note that it is possible that some per filesystem
   attributes may vary within the filesystem.  See the "homogeneous"
   attribute for its definition.  Note that the attributes
   time_access_set and time_modify_set are not listed below because they
   are write-only attributes used in a special instance of SETATTR.

TO: (because, contrary to the what the last sentence say,
	the *_set attributes are mentioned below)

5.4.  Classification of Attributes

   Each of the Mandatory and Recommended attributes can be classified in
   one of three categories: per server, per filesystem, or per
   filesystem object.  Note that it is possible that some per filesystem
   attributes may vary within the filesystem.  See the "homogeneous"
   attribute for its definition. Note that the attributes
   time_access_set and time_modify_set are not listed in
   this section because they are write-only attributes corresponding
   to time_access and time_modify, and are used in a
   special instance of SETATTR.

CHANGE:

7.4.  Multiple Roots

   The DOS and Windows operating environments are sometimes described as
   having "multiple roots".  filesystems are commonly represented as

TO: (capitalize "filesystems")

7.4.  Multiple Roots

   The DOS and Windows operating environments are sometimes described as
   having "multiple roots".  Filesystems are commonly represented as

CHANGE:

   As suggested practice, the server should apply the security policy of
   a shared resource in the server's namespace to the ancestors
   components of the namespace.  For example:

TO: (because the above is awkward, at least to me)

   As suggested practice, the server should apply the security policy of
   a shared resource in the server's namespace to the components of the
   resource's ancestors. For example:

CHANGE:

        using a similar algorithm for generate the id string, will
        generating a conflicting id string.

TO:

        using a similar algorithm for generate the id string, will
        generate a conflicting id string.

CHANGE:

        - The client machines serial number (for privacy reasons, it is
          best to perform some one way function on the serial number).

TO:

        - The client machine's serial number (for privacy reasons, it is
          best to perform some one way function on the serial number).

CHANGE:

        - A server verifier which uniquely designates a particular
        server
          instantiation.

TO: (formatting error)

        - A server verifier which uniquely designates a particular
          server instantiation.

CHANGE:

   are attempted, they are rejected with NFS4ERR_LOCKED. Assuming an
   operating environment like UNIX that requires it, when the client
   gets NFS4ERR_LOCKED on a file it knows it has the proper share
   reservation for, it will need to issue a LOCK request on the region
   of the file that includes the region the I/O was to be performed on,

TO: (because, where the OE is UNIX or not the rule still applies)

   are attempted, they are rejected with NFS4ERR_LOCKED.
   When the client
   gets NFS4ERR_LOCKED on a file it knows it has the proper share
   reservation for, it will need to issue a LOCK request on the region
   of the file that includes the region the I/O was to be performed on,

CHANGE:

   o    The server must not bestow a delegation for any open which would
        require confirmation.

   o    The server MUST NOT require confirmation on a reclaim-type open
        (i.e. one specifying claim type CLAIM_PREVIOUS or
        CLAIM_DELEGATE_PREV).

        These constraints are related in that reclaim-type opens are the
        only ones in which the server may be required to send a
        delegation.  For CLAIM_NULL, sending the delegation is optional
        while for CLAIM_DELEGATE_CUR, no delegation is sent.
        Delegations being sent with an open requiring confirmation are
        troublesome because recovering from non-confirmation adds undue
        complexity to the protocol while requiring confirmation on
        reclaim-type opens poses difficulties in that the inability to
        resolve the status of the reclaim until lease expiration may
        make it difficult to have timely determination of the set of
        locks being reclaimed (since the grace period may expire).

        Requiring open confirmation on reclaim-type opens is avoidable
        because of the nature of the environments in which such opens
        are done.  For CLAIM_PREVIOUS opens, this is immediately after
        server reboot, so there should be no time for lockowners to be
        created, found to be unused, and recycled.  For
        CLAIM_DELEGATE_PREV opens, we are dealing with a client reboot
        situation.  A server which supports delegation can be sure that
        no lockowners for that client have been recycled since client
        initialization and thus can ensure that confirmation will not be
        required.

TO: (the only change is to shift some text. "These constraints" refer
	the previous two bullet items, so the identation in the spec
	is wrong)

   o    The server must not bestow a delegation for any open which would
        require confirmation.

   o    The server MUST NOT require confirmation on a reclaim-type open
        (i.e. one specifying claim type CLAIM_PREVIOUS or
        CLAIM_DELEGATE_PREV).

   These constraints are related in that reclaim-type opens are the
   only ones in which the server may be required to send a
   delegation.  For CLAIM_NULL, sending the delegation is optional
   while for CLAIM_DELEGATE_CUR, no delegation is sent.
   Delegations being sent with an open requiring confirmation are
   troublesome because recovering from non-confirmation adds undue
   complexity to the protocol while requiring confirmation on
   reclaim-type opens poses difficulties in that the inability to
   resolve the status of the reclaim until lease expiration may
   make it difficult to have timely determination of the set of
   locks being reclaimed (since the grace period may expire).

   Requiring open confirmation on reclaim-type opens is avoidable
   because of the nature of the environments in which such opens
   are done.  For CLAIM_PREVIOUS opens, this is immediately after
   server reboot, so there should be no time for lockowners to be
   created, found to be unused, and recycled.  For
   CLAIM_DELEGATE_PREV opens, we are dealing with a client reboot
   situation.  A server which supports delegation can be sure that
   no lockowners for that client have been recycled since client
   initialization and thus can ensure that confirmation will not be
   required.

CHANGE:

   long leases are slower recovery after server failure (server must
   wait for leases to expire and grace period before granting new lock
   requests) and increased file contention (if client fails to transmit

TO:

   long leases are slower recovery after server failure (the server must
   wait for the leases to expire and the grace period to
   elapse before granting new lock requests) and increased
   file contention (if client fails to transmit

CHANGE:

   o    If GETATTR directed to two filehandles have different values of
        the fsid attribute, then the filehandles represent distinct
        objects.

TO:

   o    If GETATTR directed to two filehandles returns different values of
        the fsid attribute, then the filehandles represent distinct
        objects.

CHANGE:

   o    If GETATTR directed to the two filehandles does not return the
        fileid attribute for one or both of the handles, then it cannot

TO: (less is more)

   o    If GETATTR directed to the two filehandles does not return the
        fileid attribute for both handles, then it cannot

CHANGE:

     an owner not associated the stateid, server will return an
     NFS4ERR_LOCKED error.  The client should try to get appropriate

TO:

     an owner not associated the stateid, the server will return the
     NFS4ERR_LOCKED error.  The client should try to get appropriate

CHANGE: (in 14.2.24.  Operation 26: READDIR - Read Directory)

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

TO: (there is no attrbits argument)

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

CHANGE:

     If the server finds that the file is still open when the REMOVE
     arrives:

   o The server SHOULD NOT delete the file's directory entry if the file
     was opened with OPEN4_SHARE_DENY_WRITE or OPEN4_SHARE_DENY_BOTH.

   o If the file was not opened with OPEN4_SHARE_DENY_WRITE or
     OPEN4_SHARE_DENY_BOTH, the server SHOULD delete the file's
     directory.  However, until last CLOSE of the file, the server MAY
     continue to allow access to the file via its filehandle.

TO: (the bullet items need to be indented)

     If the server finds that the file is still open when the REMOVE
     arrives:

     o The server SHOULD NOT delete the file's directory entry if the file
       was opened with OPEN4_SHARE_DENY_WRITE or OPEN4_SHARE_DENY_BOTH.

     o If the file was not opened with OPEN4_SHARE_DENY_WRITE or
       OPEN4_SHARE_DENY_BOTH, the server SHOULD delete the file's
       directory.  However, until last CLOSE of the file, the server MAY
       continue to allow access to the file via its filehandle.

CHANGE: (in 14.2.29.  Operation 31: RESTOREFH - Restore
	Saved Filehandle)

     Set the current filehandle to the value in the saved filehandle.
     If there is no saved filehandle then return an error
     NFS4ERR_NOFILEHANDLE.

TO:

     Set the current filehandle to the value in the saved filehandle.
     If there is no saved filehandle then return an error
     NFS4ERR_RESTOREFH.

CHANGE: (in 14.2.29.  Operation 31: RESTOREFH - Restore 
        Saved Filehandle)

     NFS4ERR_NOFILEHANDLE
     NFS4ERR_RESOURCE
     NFS4ERR_RESTOREFH

TO:

     NFS4ERR_RESOURCE
     NFS4ERR_RESTOREFH

CHANGE:

     operation is inappropriate for saved filehandle. With the exception
     of READDIR, With the exception of READDIR, these operations

TO:

     operation is inappropriate for saved filehandle. With the exception
     of READDIR, these operations

CHANGE:

     The client uses SETCLIENTID operation to notify the server of its

TO:

     The client uses the SETCLIENTID operation to notify the server of its

CHANGE:

       *, s }.  Return NFS4ERR_STALE_CLIENTID.  The server does not

TO:

       *, s }.  The server returns NFS4ERR_STALE_CLIENTID.  The server does not

CHANGE:

     upgrade capability, then it pointless to try a LOCK operation to

TO:

     upgrade capability, then it is pointless to try a LOCK operation to

CHANGE (in 14.2.38.  Operation 10044: ILLEGAL - Illegal operation):

   SYNOPSIS

     <null>

TO: (so that the synopsis is consistent with other operations that
	return just a status)

   SYNOPSIS

     <null> -> ()

CHANGE (in 15.2.2.  Operation 4: CB_RECALL - Recall an Open Delegation)

   SYNOPSIS

     stateid, truncate, fh -> status

TO: (so that the synopsis is consistent with other operations that
	return just a status)

   SYNOPSIS

     stateid, truncate, fh -> ()

CHANGE:

15.2.1.  Operation 3: CB_GETATTR - Get Attributes

   SYNOPSIS

     fh, attrbits -> attrbits, attrvals

   ARGUMENT

     struct CB_GETATTR4args {
             nfs_fh4 fh;
             bitmap4 attr_request;
     };

TO:

15.2.1.  Operation 3: CB_GETATTR - Get Attributes

   SYNOPSIS

     fh, attr_request -> attrmask, attr_vals

   ARGUMENT

     struct CB_GETATTR4args {
             nfs_fh4 fh;
             bitmap4 attr_request;
     };

CHANGE:

15.2.3.  Operation 10044: CB_ILLEGAL - Illegal Callback Operation

   SYNOPSIS

     <null>

   ARGUMENT

       void;

TO:

15.2.3.  Operation 10044: CB_ILLEGAL - Illegal Callback Operation

   SYNOPSIS

     <null> -> ()

   ARGUMENT

       void;

CHANGE:

   for the transport represent by a a netid.

TO:

   for the transport represented by a netid.

CHANGE:

20.3.  Acknowledgements

   The author thanks and acknowledges:

   Neil Brown for his extensive review and comments of various drafts.
   Andy Adamson, Jim Rees, and Kendrick Smith from the CITI organization
   at the University of Michigan for their implementation efforts and
   feedback on the protocol specification.  Mike Kupfer for his review
   of the file locking and ACL mechanisms.  Alan Yoder for his input to
   ACL mechanisms.  Peter Astrand for his close review of the protocol
   specification.  Ran Atkinson for his constant reminder that user's do
   matter.

TO: 

20.3.  Acknowledgements

   The authors thank and acknowledge:

   Neil Brown for his extensive review and comments of various drafts.
   Andy Adamson, Jim Rees, and Kendrick Smith from the CITI organization
   at the University of Michigan for their implementation efforts and
   feedback on the protocol specification.  Mike Kupfer for his review
   of the file locking and ACL mechanisms.  Alan Yoder for his input to
   ACL mechanisms.  Peter Astrand for his close review of the protocol
   specification.  Ran Atkinson for his constant reminder that users do
   matter.