tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 3010

 
 
 

NFS version 4 Protocol

Part 7 of 8, p. 150 to 174
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 150 
14.2.25.  Operation 27: READLINK - Read Symbolic Link

   SYNOPSIS

      (cfh) -> linktext

   ARGUMENT

      /* CURRENT_FH: symlink */
      void;

   RESULT

      struct READLINK4resok {
              linktext4       link;
      };

      union READLINK4res switch (nfsstat4 status) {
       case NFS4_OK:
               READLINK4resok resok4;
       default:
               void;
      };

   DESCRIPTION

      READLINK reads the data associated with a symbolic link.  The data
      is a UTF-8 string that is opaque to the server.  That is, whether
      created by an NFS client or created locally on the server, the
      data in a symbolic link is not interpreted when created, but is
      simply stored.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      A symbolic link is nominally a pointer to another file.  The data
      is not necessarily interpreted by the server, just stored in the
      file.  It is possible for a client implementation to store a path
      name that is not meaningful to the server operating system in a
      symbolic link.  A READLINK operation returns the data to the
      client for interpretation. If different implementations want to
      share access to symbolic links, then they must agree on the
      interpretation of the data in the symbolic link.

      The READLINK operation is only allowed on objects of type NF4LNK.
      The server should return the error, NFS4ERR_INVAL, if the object
      is not of type, NF4LNK.

Top      Up      ToC       Page 151 
   ERRORS

      NFS4ERR_ACCES
      NFS4ERR_BADHANDLE
      NFS4ERR_DELAY
      NFS4ERR_FHEXPIRED
      NFS4ERR_INVAL
      NFS4ERR_IO
      NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_NOTSUPP
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_WRONGSEC

14.2.26.  Operation 28: REMOVE - Remove Filesystem Object

   SYNOPSIS

      (cfh), filename -> change_info

   ARGUMENT

      struct REMOVE4args {
              /* CURRENT_FH: directory */
              component4       target;
      };

   RESULT

      struct REMOVE4resok {
              change_info4    cinfo;
      }

      union REMOVE4res switch (nfsstat4 status) {
       case NFS4_OK:
               REMOVE4resok   resok4;
       default:
               void;
      }

   DESCRIPTION

      The REMOVE operation removes (deletes) a directory entry named by
      filename from the directory corresponding to the current
      filehandle.  If the entry in the directory was the last reference

Top      Up      ToC       Page 152 
      to the corresponding file system object, the object may be
      destroyed.

      For the directory where the filename was removed, the server
      returns change_info4 information in cinfo.  With the atomic field
      of the change_info4 struct, the server will indicate if the before
      and after change attributes were obtained atomically with respect
      to the removal.

      If the target has a length of 0 (zero), or if target does not obey
      the UTF-8 definition, the error NFS4ERR_INVAL will be returned.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      NFS versions 2 and 3 required a different operator RMDIR for
      directory removal.  NFS version 4 REMOVE can be used to delete any
      directory entry independent of its file type.

      The concept of last reference is server specific. However, if the
      numlinks field in the previous attributes of the object had the
      value 1, the client should not rely on referring to the object via
      a file handle. Likewise, the client should not rely on the
      resources (disk space, directory entry, and so on) formerly
      associated with the object becoming immediately available. Thus,
      if a client needs to be able to continue to access a file after
      using REMOVE to remove it, the client should take steps to make
      sure that the file will still be accessible. The usual mechanism
      used is to RENAME the file from its old name to a new hidden name.

   ERRORS

      NFS4ERR_ACCES
      NFS4ERR_BADHANDLE
      NFS4ERR_DELAY
      NFS4ERR_FHEXPIRED
      NFS4ERR_IO
      NFS4ERR_MOVED
      NFS4ERR_NAMETOOLONG
      NFS4ERR_NOENT
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_NOTDIR
      NFS4ERR_NOTEMPTY
      NFS4ERR_NOTSUPP
      NFS4ERR_RESOURCE
      NFS4ERR_ROFS
      NFS4ERR_SERVERFAULT

Top      Up      ToC       Page 153 
      NFS4ERR_STALE
      NFS4ERR_WRONGSEC

14.2.27.  Operation 29: RENAME - Rename Directory Entry

   SYNOPSIS

      (sfh), oldname (cfh), newname -> source_change_info,
      target_change_info

      ARGUMENT

      struct RENAME4args {
              /* SAVED_FH: source directory */
              component4      oldname;
              /* CURRENT_FH: target directory */
              component4      newname;
      };

   RESULT

      struct RENAME4resok {
              change_info4    source_cinfo;
              change_info4    target_cinfo;
      };

      union RENAME4res switch (nfsstat4 status) {
       case NFS4_OK:
               RENAME4resok   resok4;
       default:
               void;
      };

   DESCRIPTION

      The RENAME operation renames the object identified by oldname in
      the source directory corresponding to the saved filehandle, as set
      by the SAVEFH operation, to newname in the target directory
      corresponding to the current filehandle.  The operation is
      required to be atomic to the client.  Source and target
      directories must reside on the same file system on the server.  On
      success, the current filehandle will continue to be the target
      directory.

      If the target directory already contains an entry with the name,
      newname, the source object must be compatible with the target:
      either both are non-directories or both are directories and the
      target must be empty.  If compatible, the existing target is

Top      Up      ToC       Page 154 
      removed before the rename occurs.  If they are not compatible or
      if the target is a directory but not empty, the server will return
      the error, NFS4ERR_EXIST.

      If oldname and newname both refer to the same file (they might be
      hard links of each other), then RENAME should perform no action
      and return success.

      For both directories involved in the RENAME, the server returns
      change_info4 information.  With the atomic field of the
      change_info4 struct, the server will indicate if the before and
      after change attributes were obtained atomically with respect to
      the rename.

      If the oldname or newname has a length of 0 (zero), or if oldname
      or newname does not obey the UTF-8 definition, the error
      NFS4ERR_INVAL will be returned.

   IMPLEMENTATION

      The RENAME operation must be atomic to the client.  The statement
      "source and target directories must reside on the same file system
      on the server" means that the fsid fields in the attributes for
      the directories are the same. If they reside on different file
      systems, the error, NFS4ERR_XDEV, is returned.

      A filehandle may or may not become stale or expire on a rename.
      However, server implementors are strongly encouraged to attempt to
      keep file handles from becoming stale or expiring in this fashion.

      On some servers, the filenames, "." and "..", are illegal as
      either oldname or newname.  In addition, neither oldname nor
      newname can be an alias for the source directory.  These servers
      will return the error, NFS4ERR_INVAL, in these cases.

   ERRORS

      NFS4ERR_ACCES
      NFS4ERR_BADHANDLE
      NFS4ERR_DELAY
      NFS4ERR_DQUOT
      NFS4ERR_EXIST
      NFS4ERR_FHEXPIRED
      NFS4ERR_INVAL
      NFS4ERR_IO
      NFS4ERR_ISDIR
      NFS4ERR_MOVED
      NFS4ERR_NAMETOOLONG

Top      Up      ToC       Page 155 
      NFS4ERR_NOENT
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_NOSPC
      NFS4ERR_NOTDIR
      NFS4ERR_NOTEMPTY
      NFS4ERR_NOTSUPP
      NFS4ERR_RESOURCE
      NFS4ERR_ROFS
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_WRONGSEC
      NFS4ERR_XDEV

14.2.28.  Operation 30: RENEW - Renew a Lease

   SYNOPSIS

      stateid -> ()

   ARGUMENT

      struct RENEW4args {
              stateid4        stateid;
      };

   RESULT

      struct RENEW4res {
              nfsstat4        status;
      };

   DESCRIPTION

      The RENEW operation is used by the client to renew leases which it
      currently holds at a server.  In processing the RENEW request, the
      server renews all leases associated with the client.  The
      associated leases are determined by the client id provided via the
      SETCLIENTID procedure.

      The stateid for RENEW may not be one of the special stateids
      consisting of all bits 0 (zero) or all bits 1.

   IMPLEMENTATION

   ERRORS

      NFS4ERR_BAD_STATEID
      NFS4ERR_EXPIRED

Top      Up      ToC       Page 156 
      NFS4ERR_GRACE
      NFS4ERR_INVAL
      NFS4ERR_LEASE_MOVED
      NFS4ERR_MOVED
      NFS4ERR_OLD_STATEID
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE_STATEID
      NFS4ERR_WRONGSEC

14.2.29.  Operation 31: RESTOREFH - Restore Saved Filehandle

   SYNOPSIS

      (sfh) -> (cfh)

   ARGUMENT

      /* SAVED_FH: */
      void;

   RESULT

      struct RESTOREFH4res {
              /* CURRENT_FH: value of saved fh */
              nfsstat4        status;
      };

   DESCRIPTION

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

   IMPLEMENTATION

      Operations like OPEN and LOOKUP use the current filehandle to
      represent a directory and replace it with a new filehandle.
      Assuming the previous filehandle was saved with a SAVEFH operator,
      the previous filehandle can be restored as the current filehandle.
      This is commonly used to obtain post-operation attributes for the
      directory, e.g.

               PUTFH (directory filehandle)
               SAVEFH
               GETATTR attrbits     (pre-op dir attrs)
               CREATE optbits "foo" attrs
               GETATTR attrbits     (file attributes)

Top      Up      ToC       Page 157 
               RESTOREFH
               GETATTR attrbits     (post-op dir attrs)

   ERRORS

      NFS4ERR_BADHANDLE
      NFS4ERR_FHEXPIRED
      NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_WRONGSEC

14.2.30.  Operation 32: SAVEFH - Save Current Filehandle

   SYNOPSIS

      (cfh) -> (sfh)

   ARGUMENT

      /* CURRENT_FH: */
      void;

   RESULT

      struct SAVEFH4res {
              /* SAVED_FH: value of current fh */
              nfsstat4        status;
      };

      DESCRIPTION

      Save the current filehandle.  If a previous filehandle was saved
      then it is no longer accessible.  The saved filehandle can be
      restored as the current filehandle with the RESTOREFH operator.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

   ERRORS

      NFS4ERR_BADHANDLE
      NFS4ERR_FHEXPIRED
      NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE

Top      Up      ToC       Page 158 
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_WRONGSEC

14.2.31.  Operation 33: SECINFO - Obtain Available Security

   SYNOPSIS

      (cfh), name -> { secinfo }

   ARGUMENT

      struct SECINFO4args {
              /* CURRENT_FH: */
              component4     name;
      };

   RESULT

      enum rpc_gss_svc_t {
              RPC_GSS_SVC_NONE        = 1,
              RPC_GSS_SVC_INTEGRITY   = 2,
              RPC_GSS_SVC_PRIVACY     = 3
      };

      struct rpcsec_gss_info {
              sec_oid4        oid;
              qop4            qop;
              rpc_gss_svc_t   service;
      };

      struct secinfo4 {
              uint32_t flavor;
              opaque flavor_info<>;   /* null for AUTH_SYS, AUTH_NONE;
                                         contains rpcsec_gss_info for
                                         RPCSEC_GSS. */
      };

      typedef secinfo4 SECINFO4resok<>;

      union SECINFO4res switch (nfsstat4 status) {
       case NFS4_OK:
               SECINFO4resok resok4;
       default:
               void;
      };

Top      Up      ToC       Page 159 
   DESCRIPTION

      The SECINFO operation is used by the client to obtain a list of
      valid RPC authentication flavors for a specific file handle, file
      name pair.  The result will contain an array which represents the
      security mechanisms available.  The array entries are represented
      by the secinfo4 structure.  The field 'flavor' will contain a
      value of AUTH_NONE, AUTH_SYS (as defined in [RFC1831]), or
      RPCSEC_GSS (as defined in [RFC2203]).

      For the flavors, AUTH_NONE, and AUTH_SYS no additional security
      information is returned.  For a return value of RPCSEC_GSS, a
      security triple is returned that contains the mechanism object id
      (as defined in [RFC2078]), the quality of protection (as defined
      in [RFC2078]) and the service type (as defined in [RFC2203]).  It
      is possible for SECINFO to return multiple entries with flavor
      equal to RPCSEC_GSS with different security triple values.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      The SECINFO operation is expected to be used by the NFS client
      when the error value of NFS4ERR_WRONGSEC is returned from another
      NFS operation.  This signifies to the client that the server's
      security policy is different from what the client is currently
      using.  At this point, the client is expected to obtain a list of
      possible security flavors and choose what best suits its policies.

      It is recommended that the client issue the SECINFO call protected
      by a security triple that uses either rpc_gss_svc_integrity or
      rpc_gss_svc_privacy service. The use of rpc_gss_svc_none would
      allow an attacker in the middle to modify the SECINFO results such
      that the client might select a weaker algorithm in the set allowed
      by server, making the client and/or server vulnerable to further
      attacks.

   ERRORS

      NFS4ERR_BADHANDLE
      NFS4ERR_FHEXPIRED
      NFS4ERR_MOVED
      NFS4ERR_NAMETOOLONG
      NFS4ERR_NOENT
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_NOTDIR
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT

Top      Up      ToC       Page 160 
      NFS4ERR_STALE
      NFS4ERR_WRONGSEC

14.2.32.  Operation 34: SETATTR - Set Attributes

   SYNOPSIS

      (cfh), attrbits, attrvals -> -

   ARGUMENT

      struct SETATTR4args {
              /* CURRENT_FH: target object */
              stateid4        stateid;
              fattr4          obj_attributes;
      };

   RESULT

      struct SETATTR4res {
              nfsstat4        status;
              bitmap4         attrsset;
      };

   DESCRIPTION

      The SETATTR operation changes one or more of the attributes of a
      file system object.  The new attributes are specified with a
      bitmap and the attributes that follow the bitmap in bit order.

      The stateid is necessary for SETATTRs that change the size of a
      file (modify the attribute object_size).  This stateid represents
      a record lock, share reservation, or delegation which must be
      valid for the SETATTR to modify the file data.  A valid stateid
      would always be specified.  When the file size is not changed, the
      special stateid consisting of all bits 0 (zero) should be used.

      On either success or failure of the operation, the server will
      return the attrsset bitmask to represent what (if any) attributes
      were successfully set.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      The file size attribute is used to request changes to the size of
      a file. A value of 0 (zero) causes the file to be truncated, a
      value less than the current size of the file causes data from new

Top      Up      ToC       Page 161 
      size to the end of the file to be discarded, and a size greater
      than the current size of the file causes logically zeroed data
      bytes to be added to the end of the file.  Servers are free to
      implement this using holes or actual zero data bytes. Clients
      should not make any assumptions regarding a server's
      implementation of this feature, beyond that the bytes returned
      will be zeroed.  Servers must support extending the file size via
      SETATTR.

      SETATTR is not guaranteed atomic.  A failed SETATTR may partially
      change a file's attributes.

      Changing the size of a file with SETATTR indirectly changes the
      time_modify.  A client must account for this as size changes can
      result in data deletion.

      If server and client times differ, programs that compare client
      time to file times can break. A time maintenance protocol should
      be used to limit client/server time skew.

      If the server cannot successfully set all the attributes it must
      return an NFS4ERR_INVAL error.  If the server can only support 32
      bit offsets and sizes, a SETATTR request to set the size of a file
      to larger than can be represented in 32 bits will be rejected with
      this same error.

   ERRORS

      NFS4ERR_ACCES
      NFS4ERR_BADHANDLE
      NFS4ERR_BAD_STATEID
      NFS4ERR_DELAY
      NFS4ERR_DENIED
      NFS4ERR_DQUOT
      NFS4ERR_EXPIRED
      NFS4ERR_FBIG
      NFS4ERR_FHEXPIRED
      NFS4ERR_GRACE
      NFS4ERR_INVAL
      NFS4ERR_IO
      NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_NOSPC
      NFS4ERR_NOTSUPP
      NFS4ERR_OLD_STATEID
      NFS4ERR_PERM
      NFS4ERR_RESOURCE
      NFS4ERR_ROFS

Top      Up      ToC       Page 162 
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_STALE_STATEID
      NFS4ERR_WRONGSEC

14.2.33.  Operation 35: SETCLIENTID - Negotiate Clientid

   SYNOPSIS

      client, callback -> clientid, setclientid_confirm

   ARGUMENT

      struct SETCLIENTID4args {
              nfs_client_id4  client;
              cb_client4      callback;
      };

   RESULT

      struct SETCLIENTID4resok {
              clientid4       clientid;
              verifier4       setclientid_confirm;
      };

      union SETCLIENTID4res switch (nfsstat4 status) {
       case NFS4_OK:
               SETCLIENTID4resok      resok4;
       case NFS4ERR_CLID_INUSE:
               clientaddr4    client_using;
       default:
               void;
      };

   DESCRIPTION

      The SETCLIENTID operation introduces the ability of the client to
      notify the server of its intention to use a particular client
      identifier and verifier pair.  Upon successful completion the
      server will return a clientid which is used in subsequent file
      locking requests and a confirmation verifier.  The client will use
      the SETCLIENTID_CONFIRM operation to return the verifier to the
      server.  At that point, the client may use the clientid in
      subsequent operations that require an nfs_lockowner.

Top      Up      ToC       Page 163 
      The callback information provided in this operation will be used
      if the client is provided an open delegation at a future point.
      Therefore, the client must correctly reflect the program and port
      numbers for the callback program at the time SETCLIENTID is used.

   IMPLEMENTATION

      The server takes the verifier and client identification supplied
      in the nfs_client_id4 and searches for a match of the client
      identification.  If no match is found the server saves the
      principal/uid information along with the verifier and client
      identification and returns a unique clientid that is used as a
      shorthand reference to the supplied information.

      If the server finds matching client identification and a
      corresponding match in principal/uid, the server releases all
      locking state for the client and returns a new clientid.

      The principal, or principal to user-identifier mapping is taken
      from the credential presented in the RPC.  As mentioned, the
      server will use the credential and associated principal for the
      matching with existing clientids.  If the client is a traditional
      host-based client like a Unix NFS client, then the credential
      presented may be the host credential.  If the client is a user
      level client or lightweight client, the credential used may be the
      end user's credential.  The client should take care in choosing an
      appropriate credential since denial of service attacks could be
      attempted by a rogue client that has access to the credential.

   ERRORS

      NFS4ERR_CLID_INUSE
      NFS4ERR_INVAL
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT

14.2.34.  Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid

   SYNOPSIS

      setclientid_confirm -> -

   ARGUMENT

      struct SETCLIENTID_CONFIRM4args {
              verifier4       setclientid_confirm;
      };

Top      Up      ToC       Page 164 
   RESULT

      struct SETCLIENTID_CONFIRM4res {
              nfsstat4        status;
      };

   DESCRIPTION

      This operation is used by the client to confirm the results from a
      previous call to SETCLIENTID.  The client provides the server
      supplied (from a SETCLIENTID response) opaque confirmation
      verifier.  The server responds with a simple status of success or
      failure.

   IMPLEMENTATION

      The client must use the SETCLIENTID_CONFIRM operation to confirm
      its use of client identifier.  If the server is holding state for
      a client which has presented a new verifier via SETCLIENTID, then
      the state will not be released, as described in the section
      "Client Failure and Recovery", until a valid SETCLIENTID_CONFIRM
      is received.  Upon successful confirmation the server will release
      the previous state held on behalf of the client.  The server
      should choose a confirmation cookie value that is reasonably
      unique for the client.

   ERRORS

      NFS4ERR_CLID_INUSE
      NFS4ERR_INVAL
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE_CLIENTID

14.2.35.  Operation 37: VERIFY - Verify Same Attributes

   SYNOPSIS

      (cfh), fattr -> -

   ARGUMENT

      struct VERIFY4args {
              /* CURRENT_FH: object */
              fattr4          obj_attributes;
      };

Top      Up      ToC       Page 165 
   RESULT

      struct VERIFY4res {
              nfsstat4        status;
      };

   DESCRIPTION

      The VERIFY operation is used to verify that attributes have a
      value assumed by the client before proceeding with following
      operations in the compound request.  If any of the attributes do
      not match then the error NFS4ERR_NOT_SAME must be returned.  The
      current filehandle retains its value after successful completion
      of the operation.

   IMPLEMENTATION

      One possible use of the VERIFY operation is the following compound
      sequence.  With this the client is attempting to verify that the
      file being removed will match what the client expects to be
      removed.  This sequence can help prevent the unintended deletion
      of a file.

               PUTFH (directory filehandle)
               LOOKUP (file name)
               VERIFY (filehandle == fh)
               PUTFH (directory filehandle)
               REMOVE (file name)

      This sequence does not prevent a second client from removing and
      creating a new file in the middle of this sequence but it does
      help avoid the unintended result.

      In the case that a recommended attribute is specified in the
      VERIFY operation and the server does not support that attribute
      for the file system object, the error NFS4ERR_NOTSUPP is returned
      to the client.

   ERRORS

      NFS4ERR_ACCES
      NFS4ERR_BADHANDLE
      NFS4ERR_DELAY
      NFS4ERR_FHEXPIRED
      NFS4ERR_INVAL
      NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_NOTSUPP

Top      Up      ToC       Page 166 
      NFS4ERR_NOT_SAME
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_WRONGSEC

14.2.36.  Operation 38: WRITE - Write to File

   SYNOPSIS

      (cfh), offset, count, stability, stateid, data -> count, committed,
      verifier

   ARGUMENT

      enum stable_how4 {
              UNSTABLE4       = 0,
              DATA_SYNC4      = 1,
              FILE_SYNC4      = 2
      };

      struct WRITE4args {
              /* CURRENT_FH: file */
              stateid4        stateid;
              offset4         offset;
              stable_how4     stable;
              opaque          data<>;
      };

   RESULT

      struct WRITE4resok {
              count4          count;
              stable_how4     committed;
              verifier4       writeverf;
      };

      union WRITE4res switch (nfsstat4 status) {
       case NFS4_OK:
               WRITE4resok    resok4;
       default:
               void;
      };

Top      Up      ToC       Page 167 
   DESCRIPTION

      The WRITE operation is used to write data to a regular file.  The
      target file is specified by the current filehandle.  The offset
      specifies the offset where the data should be written.  An offset
      of 0 (zero) specifies that the write should start at the beginning
      of the file.  The count represents the number of bytes of data
      that are to be written.  If the count is 0 (zero), the WRITE will
      succeed and return a count of 0 (zero) subject to permissions
      checking.  The server may choose to write fewer bytes than
      requested by the client.

      Part of the write request is a specification of how the write is
      to be performed.  The client specifies with the stable parameter
      the method of how the data is to be processed by the server.  If
      stable is FILE_SYNC4, the server must commit the data written plus
      all file system metadata to stable storage before returning
      results.  This corresponds to the NFS version 2 protocol
      semantics.  Any other behavior constitutes a protocol violation.
      If stable is DATA_SYNC4, then the server must commit all of the
      data to stable storage and enough of the metadata to retrieve the
      data before returning.  The server implementor is free to
      implement DATA_SYNC4 in the same fashion as FILE_SYNC4, but with a
      possible performance drop.  If stable is UNSTABLE4, the server is
      free to commit any part of the data and the metadata to stable
      storage, including all or none, before returning a reply to the
      client. There is no guarantee whether or when any uncommitted data
      will subsequently be committed to stable storage. The only
      guarantees made by the server are that it will not destroy any
      data without changing the value of verf and that it will not
      commit the data and metadata at a level less than that requested
      by the client.

      The stateid returned from a previous record lock or share
      reservation request is provided as part of the argument.  The
      stateid is used by the server to verify that the associated lock
      is still valid and to update lease timeouts for the client.

      Upon successful completion, the following results are returned.
      The count result is the number of bytes of data written to the
      file. The server may write fewer bytes than requested. If so, the
      actual number of bytes written starting at location, offset, is
      returned.

      The server also returns an indication of the level of commitment
      of the data and metadata via committed. If the server committed
      all data and metadata to stable storage, committed should be set
      to FILE_SYNC4. If the level of commitment was at least as strong

Top      Up      ToC       Page 168 
      as DATA_SYNC4, then committed should be set to DATA_SYNC4.
      Otherwise, committed must be returned as UNSTABLE4. If stable was
      FILE4_SYNC, then committed must also be FILE_SYNC4: anything else
      constitutes a protocol violation. If stable was DATA_SYNC4, then
      committed may be FILE_SYNC4 or DATA_SYNC4: anything else
      constitutes a protocol violation. If stable was UNSTABLE4, then
      committed may be either FILE_SYNC4, DATA_SYNC4, or UNSTABLE4.

      The final portion of the result is the write verifier, verf.  The
      write verifier is a cookie that the client can use to determine
      whether the server has changed state between a call to WRITE and a
      subsequent call to either WRITE or COMMIT.  This cookie must be
      consistent during a single instance of the NFS version 4 protocol
      service and must be unique between instances of the NFS version 4
      protocol server, where uncommitted data may be lost.

      If a client writes data to the server with the stable argument set
      to UNSTABLE4 and the reply yields a committed response of
      DATA_SYNC4 or UNSTABLE4, the client will follow up some time in
      the future with a COMMIT operation to synchronize outstanding
      asynchronous data and metadata with the server's stable storage,
      barring client error. It is possible that due to client crash or
      other error that a subsequent COMMIT will not be received by the
      server.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      It is possible for the server to write fewer than count bytes of
      data.  In this case, the server should not return an error unless
      no data was written at all.  If the server writes less than count
      bytes, the client should issue another WRITE to write the
      remaining data.

      It is assumed that the act of writing data to a file will cause
      the time_modified of the file to be updated.  However, the
      time_modified of the file should not be changed unless the
      contents of the file are changed.  Thus, a WRITE request with
      count set to 0 should not cause the time_modified of the file to
      be updated.

      The definition of stable storage has been historically a point of
      contention.  The following expected properties of stable storage
      may help in resolving design issues in the implementation. Stable
      storage is persistent storage that survives:

Top      Up      ToC       Page 169 
               1. Repeated power failures.
               2. Hardware failures (of any board, power supply, etc.).
               3. Repeated software crashes, including reboot cycle.

      This definition does not address failure of the stable storage
      module itself.

      The verifier is defined to allow a client to detect different
      instances of an NFS version 4 protocol server over which cached,
      uncommitted data may be lost. In the most likely case, the
      verifier allows the client to detect server reboots.  This
      information is required so that the client can safely determine
      whether the server could have lost cached data.  If the server
      fails unexpectedly and the client has uncommitted data from
      previous WRITE requests (done with the stable argument set to
      UNSTABLE4 and in which the result committed was returned as
      UNSTABLE4 as well) it may not have flushed cached data to stable
      storage. The burden of recovery is on the client and the client
      will need to retransmit the data to the server.

      A suggested verifier would be to use the time that the server was
      booted or the time the server was last started (if restarting the
      server without a reboot results in lost buffers).

      The committed field in the results allows the client to do more
      effective caching.  If the server is committing all WRITE requests
      to stable storage, then it should return with committed set to
      FILE_SYNC4, regardless of the value of the stable field in the
      arguments. A server that uses an NVRAM accelerator may choose to
      implement this policy.  The client can use this to increase the
      effectiveness of the cache by discarding cached data that has
      already been committed on the server.

      Some implementations may return NFS4ERR_NOSPC instead of
      NFS4ERR_DQUOT when a user's quota is exceeded.

   ERRORS

      NFS4ERR_ACCES
      NFS4ERR_BADHANDLE
      NFS4ERR_BAD_STATEID
      NFS4ERR_DELAY
      NFS4ERR_DENIED
      NFS4ERR_DQUOT
      NFS4ERR_EXPIRED
      NFS4ERR_FBIG
      NFS4ERR_FHEXPIRED
      NFS4ERR_GRACE

Top      Up      ToC       Page 170 
      NFS4ERR_INVAL
      NFS4ERR_IO
      NFS4ERR_LEASE_MOVED
      NFS4ERR_LOCKED
      NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_NOSPC
      NFS4ERR_OLD_STATEID
      NFS4ERR_RESOURCE
      NFS4ERR_ROFS
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_STALE_STATEID
      NFS4ERR_WRONGSEC

15.  NFS Version 4 Callback Procedures

   The procedures used for callbacks are defined in the following
   sections.  In the interest of clarity, the terms "client" and
   "server" refer to NFS clients and servers, despite the fact that for
   an individual callback RPC, the sense of these terms would be
   precisely the opposite.

15.1.  Procedure 0: CB_NULL - No Operation

   SYNOPSIS

      <null>

   ARGUMENT

      void;

   RESULT

      void;

   DESCRIPTION

      Standard NULL procedure.  Void argument, void response.  Even
      though there is no direct functionality associated with this
      procedure, the server will use CB_NULL to confirm the existence of
      a path for RPCs from server to client.

   ERRORS

      None.

Top      Up      ToC       Page 171 
15.2.  Procedure 1: CB_COMPOUND - Compound Operations

   SYNOPSIS

      compoundargs -> compoundres

   ARGUMENT

      enum nfs_cb_opnum4 {
              OP_CB_GETATTR           = 3,
              OP_CB_RECALL            = 4 };

      union nfs_cb_argop4 switch (unsigned argop) {
       case OP_CB_GETATTR:    CB_GETATTR4args opcbgetattr;
       case OP_CB_RECALL:     CB_RECALL4args  opcbrecall; };

      struct CB_COMPOUND4args {
              utf8string      tag;
              uint32_t        minorversion;
              nfs_cb_argop4   argarray<>; };

   RESULT

      union nfs_cb_resop4 switch (unsigned resop){
       case OP_CB_GETATTR:    CB_GETATTR4res  opcbgetattr;
       case OP_CB_RECALL:     CB_RECALL4res   opcbrecall; };

      struct CB_COMPOUND4res {
              nfsstat4 status;
              utf8string      tag;
              nfs_cb_resop4   resarray<>; };

   DESCRIPTION

      The CB_COMPOUND procedure is used to combine one or more of the
      callback procedures into a single RPC request.  The main callback
      RPC program has two main procedures: CB_NULL and CB_COMPOUND.  All
      other operations use the CB_COMPOUND procedure as a wrapper.

      In the processing of the CB_COMPOUND procedure, the client may
      find that it does not have the available resources to execute any
      or all of the operations within the CB_COMPOUND sequence.  In this
      case, the error NFS4ERR_RESOURCE will be returned for the
      particular operation within the CB_COMPOUND procedure where the
      resource exhaustion occurred.  This assumes that all previous
      operations within the CB_COMPOUND sequence have been evaluated
      successfully.

Top      Up      ToC       Page 172 
      Contained within the CB_COMPOUND results is a 'status' field.
      This status must be equivalent to the status of the last operation
      that was executed within the CB_COMPOUND procedure.  Therefore, if
      an operation incurred an error then the 'status' value will be the
      same error value as is being returned for the operation that
      failed.

   IMPLEMENTATION

      The CB_COMPOUND procedure is used to combine individual operations
      into a single RPC request.  The client interprets each of the
      operations in turn.  If an operation is executed by the client and
      the status of that operation is NFS4_OK, then the next operation
      in the CB_COMPOUND procedure is executed.  The client continues
      this process until there are no more operations to be executed or
      one of the operations has a status value other than NFS4_OK.

   ERRORS

      NFS4ERR_BADHANDLE
      NFS4ERR_BAD_STATEID
      NFS4ERR_RESOURCE

15.2.1.  Operation 3: CB_GETATTR - Get Attributes

   SYNOPSIS

      fh, attrbits -> attrbits, attrvals

   ARGUMENT

      struct CB_GETATTR4args {
              nfs_fh4 fh;
              bitmap4 attr_request;
      };

   RESULT

      struct CB_GETATTR4resok {
              fattr4  obj_attributes;
      };

      union CB_GETATTR4res switch (nfsstat4 status) {
       case NFS4_OK:
               CB_GETATTR4resok       resok4;
       default:
               void;
      };

Top      Up      ToC       Page 173 
   DESCRIPTION

      The CB_GETATTR operation is used to obtain the attributes modified
      by an open delegate to allow the server to respond to GETATTR
      requests for a file which is the subject of an open delegation.

      If the handle specified is not one for which the client holds a
      write open delegation, an NFS4ERR_BADHANDLE error is returned.

   IMPLEMENTATION

      The client returns attrbits and the associated attribute values
      only for attributes that it may change (change, time_modify,
      object_size).

   ERRORS

      NFS4ERR_BADHANDLE
      NFS4ERR_RESOURCE

15.2.2.  Operation 4: CB_RECALL - Recall an Open Delegation

   SYNOPSIS

      stateid, truncate, fh -> status

   ARGUMENT

      struct CB_RECALL4args {
              stateid4        stateid;
              bool            truncate;
              nfs_fh4         fh;
      };

   RESULT

      struct CB_RECALL4res {
              nfsstat4        status;
      };

   DESCRIPTION

      The CB_RECALL operation is used to begin the process of recalling
      an open delegation and returning it to the server.

Top      Up      ToC       Page 174 
      The truncate flag is used to optimize recall for a file which is
      about to be truncated to zero.  When it is set, the client is
      freed of obligation to propagate modified data for the file to the
      server, since this data is irrelevant.

      If the handle specified is not one for which the client holds an
      open delegation, an NFS4ERR_BADHANDLE error is returned.

      If the stateid specified is not one corresponding to an open
      delegation for the file specified by the filehandle, an
      NFS4ERR_BAD_STATEID is returned.

   IMPLEMENTATION

      The client should reply to the callback immediately.  Replying
      does not complete the recall.  The recall is not complete until
      the delegation is returned using a DELEGRETURN.

   ERRORS

      NFS4ERR_BADHANDLE
      NFS4ERR_BAD_STATEID
      NFS4ERR_RESOURCE

16.  Security Considerations

   The major security feature to consider is the authentication of the
   user making the request of NFS service.  Consideration should also be
   given to the integrity and privacy of this NFS request.  These
   specific issues are discussed as part of the section on "RPC and
   Security Flavor".

17.  IANA Considerations

17.1.  Named Attribute Definition

   The NFS version 4 protocol provides for the association of named
   attributes to files.  The name space identifiers for these attributes
   are defined as string names.  The protocol does not define the
   specific assignment of the name space for these file attributes; the
   application developer or system vendor is allowed to define the
   attribute, its semantics, and the associated name.  Even though this
   name space will not be specifically controlled to prevent collisions,
   the application developer or system vendor is strongly encouraged to
   provide the name assignment and associated semantics for attributes
   via an Informational RFC.  This will provide for interoperability
   where common interests exist.


Next RFC Part