14.  NFS Version 4 Procedures

14.1.  Procedure 0: NULL - No Operation

   SYNOPSIS

      <null>

   ARGUMENT

      void;


   RESULT

      void;

   DESCRIPTION

      Standard NULL procedure.  Void argument, void response.  This
      procedure has no functionality associated with it.  Because of
      this it is sometimes used to measure the overhead of processing a
      service request.  Therefore, the server should ensure that no
      unnecessary work is done in servicing this procedure.

   ERRORS

      None.

14.2.  Procedure 1: COMPOUND - Compound Operations

   SYNOPSIS

      compoundargs -> compoundres

   ARGUMENT

      union nfs_argop4 switch (nfs_opnum4 argop) {
              case <OPCODE>: <argument>;
              ...
      };

      struct COMPOUND4args {
              utf8string      tag;
              uint32_t        minorversion;
              nfs_argop4      argarray<>;
      };

   RESULT

         union nfs_resop4 switch (nfs_opnum4 resop){
                 case <OPCODE>: <result>;
                 ...
         };

         struct COMPOUND4res {
                 nfsstat4        status;
                 utf8string      tag;
                 nfs_resop4      resarray<>;
         };

   DESCRIPTION

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

      The COMPOUND procedure is used to combine individual operations
      into a single RPC request.  The server interprets each of the
      operations in turn.  If an operation is executed by the server and
      the status of that operation is NFS4_OK, then the next operation
      in the COMPOUND procedure is executed.  The server 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.

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

      The COMPOUND arguments contain a "minorversion" field.  The
      initial and default value for this field is 0 (zero).  This field
      will be used by future minor versions such that the client can
      communicate to the server what minor version is being requested.

      If the server receives a COMPOUND procedure with a minorversion
      field value that it does not support, the server MUST return an
      error of NFS4ERR_MINOR_VERS_MISMATCH and a zero length resultdata
      array.

      Contained within the COMPOUND results is a "status" field.  If the
      results array length is non-zero, this status must be equivalent
      to the status of the last operation that was executed within the
      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.

      Note that operations, 0 (zero) and 1 (one) are not defined for the
      COMPOUND procedure.  If the server receives an operation array
      with either of these included, an error of NFS4ERR_NOTSUPP must be
      returned.  Operation 2 is not defined but reserved for future
      definition and use with minor versioning.  If the server receives
      a operation array that contains operation 2 and the minorversion
      field has a value of 0 (zero), an error of NFS4ERR_NOTSUPP is
      returned.  If an operation array contains an operation 2 and the
      minorversion field is non-zero and the server does not support the
      minor version, the server returns an error of
      NFS4ERR_MINOR_VERS_MISMATCH.  Therefore, the
      NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other
      errors.

   IMPLEMENTATION

      Note that the definition of the "tag" in both the request and
      response are left to the implementor.  It may be used to summarize
      the content of the compound request for the benefit of packet
      sniffers and engineers debugging implementations.

      Since an error of any type may occur after only a portion of the
      operations have been evaluated, the client must be prepared to
      recover from any failure.  If the source of an NFS4ERR_RESOURCE
      error was a complex or lengthy set of operations, it is likely
      that if the number of operations were reduced the server would be
      able to evaluate them successfully.  Therefore, the client is
      responsible for dealing with this type of complexity in recovery.

   ERRORS

      All errors defined in the protocol

14.2.1.  Operation 3: ACCESS - Check Access Rights

   SYNOPSIS

         (cfh), accessreq -> supported, accessrights

   ARGUMENT

         const ACCESS4_READ      = 0x00000001;
         const ACCESS4_LOOKUP    = 0x00000002;
         const ACCESS4_MODIFY    = 0x00000004;
         const ACCESS4_EXTEND    = 0x00000008;
         const ACCESS4_DELETE    = 0x00000010;
         const ACCESS4_EXECUTE   = 0x00000020;

         struct ACCESS4args {
                 /* CURRENT_FH: object */
                 uint32_t        access;
         };

   RESULT

         struct ACCESS4resok {
                 uint32_t        supported;
                 uint32_t        access;
         };

         union ACCESS4res switch (nfsstat4 status) {
          case NFS4_OK:
                  ACCESS4resok   resok4;
          default:
                  void;
         };

   DESCRIPTION

      ACCESS determines the access rights that a user, as identified by
      the credentials in the RPC request, has with respect to the file
      system object specified by the current filehandle.  The client
      encodes the set of access rights that are to be checked in the bit
      mask "access".  The server checks the permissions encoded in the
      bit mask.  If a status of NFS4_OK is returned, two bit masks are
      included in the response.  The first, "supported", represents the
      access rights for which the server can verify reliably.  The
      second, "access", represents the access rights available to the
      user for the filehandle provided.  On success, the current
      filehandle retains its value.

      Note that the supported field will contain only as many values as
      was originally sent in the arguments.  For example, if the client
      sends an ACCESS operation with only the ACCESS4_READ value set and
      the server supports this value, the server will return only
      ACCESS4_READ even if it could have reliably checked other values.

      The results of this operation are necessarily advisory in nature.
      A return status of NFS4_OK and the appropriate bit set in the bit
      mask does not imply that such access will be allowed to the file
      system object in the future. This is because access rights can be
      revoked by the server at any time.

      The following access permissions may be requested:

   ACCESS4_READ    Read data from file or read a directory.

   ACCESS4_LOOKUP  Look up a name in a directory (no meaning for non-
                   directory objects).

   ACCESS4_MODIFY  Rewrite existing file data or modify existing
                   directory entries.

   ACCESS4_EXTEND  Write new data or add directory entries.

   ACCESS4_DELETE  Delete an existing directory entry (no meaning for
                   non-directory objects).

   ACCESS4_EXECUTE Execute file (no meaning for a directory).

   On success, the current filehandle retains its value.

   IMPLEMENTATION

      For the NFS version 4 protocol, the use of the ACCESS procedure
      when opening a regular file is deprecated in favor of using OPEN.

      In general, it is not sufficient for the client to attempt to
      deduce access permissions by inspecting the uid, gid, and mode
      fields in the file attributes or by attempting to interpret the
      contents of the ACL attribute.  This is because the server may
      perform uid or gid mapping or enforce additional access control
      restrictions.  It is also possible that the server may not be in
      the same ID space as the client.  In these cases (and perhaps
      others), the client can not reliably perform an access check with
      only current file attributes.

      In the NFS version 2 protocol, the only reliable way to determine
      whether an operation was allowed was to try it and see if it
      succeeded or failed.  Using the ACCESS procedure in the NFS
      version 4 protocol, the client can ask the server to indicate
      whether or not one or more classes of operations are permitted.
      The ACCESS operation is provided to allow clients to check before
      doing a series of operations which will result in an access
      failure.  The OPEN operation provides a point where the server can
      verify access to the file object and method to return that
      information to the client.  The ACCESS operation is still useful
      for directory operations or for use in the case the UNIX API
      "access" is used on the client.

      The information returned by the server in response to an ACCESS
      call is not permanent.  It was correct at the exact time that the
      server performed the checks, but not necessarily afterwards.  The
      server can revoke access permission at any time.

      The client should use the effective credentials of the user to
      build the authentication information in the ACCESS request used to
      determine access rights.  It is the effective user and group
      credentials that are used in subsequent read and write operations.

      Many implementations do not directly support the ACCESS4_DELETE
      permission.  Operating systems like UNIX will ignore the
      ACCESS4_DELETE bit if set on an access request on a non-directory
      object.  In these systems, delete permission on a file is
      determined by the access permissions on the directory in which the
      file resides, instead of being determined by the permissions of
      the file itself.  Therefore, the mask returned enumerating which
      access rights can be determined will have the ACCESS4_DELETE value
      set to 0.  This indicates to the client that the server was unable
      to check that particular access right.  The ACCESS4_DELETE bit in
      the access mask returned will then be ignored by the client.

   ERRORS

         NFS4ERR_ACCES
         NFS4ERR_BADHANDLE
         NFS4ERR_DELAY
         NFS4ERR_FHEXPIRED
         NFS4ERR_IO
         NFS4ERR_MOVED
         NFS4ERR_NOFILEHANDLE
         NFS4ERR_RESOURCE
         NFS4ERR_SERVERFAULT
         NFS4ERR_STALE
         NFS4ERR_WRONGSEC

14.2.2.  Operation 4: CLOSE - Close File

   SYNOPSIS

         (cfh), seqid, stateid -> stateid

   ARGUMENT

         struct CLOSE4args {
                 /* CURRENT_FH: object */
                 seqid4          seqid
                 stateid4        stateid;
         };

   RESULT

         union CLOSE4res switch (nfsstat4 status) {
          case NFS4_OK:
                  stateid4       stateid;
          default:
                  void;
         };

   DESCRIPTION

      The CLOSE operation releases share reservations for the file as
      specified by the current filehandle.  The share reservations and
      other state information released at the server as a result of this
      CLOSE is only associated with the supplied stateid.  The sequence
      id provides for the correct ordering. State associated with other
      OPENs is not affected.

      If record locks are held, the client SHOULD release all locks
      before issuing a CLOSE.  The server MAY free all outstanding locks
      on CLOSE but some servers may not support the CLOSE of a file that
      still has record locks held.  The server MUST return failure if
      any locks would exist after the CLOSE.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      ERRORS

         NFS4ERR_BADHANDLE
         NFS4ERR_BAD_SEQID
         NFS4ERR_BAD_STATEID
         NFS4ERR_DELAY

         NFS4ERR_EXPIRED
         NFS4ERR_FHEXPIRED
         NFS4ERR_GRACE
         NFS4ERR_INVAL
         NFS4ERR_ISDIR
         NFS4ERR_LEASE_MOVED
         NFS4ERR_MOVED
         NFS4ERR_NOFILEHANDLE
         NFS4ERR_OLD_STATEID
         NFS4ERR_RESOURCE
         NFS4ERR_SERVERFAULT
         NFS4ERR_STALE
         NFS4ERR_STALE_STATEID

14.2.3.  Operation 5: COMMIT - Commit Cached Data

   SYNOPSIS

         (cfh), offset, count -> verifier

   ARGUMENT

         struct COMMIT4args {
                 /* CURRENT_FH: file */
                 offset4         offset;
                 count4          count;
         };

   RESULT

         struct COMMIT4resok {
                 verifier4       writeverf;
         };

         union COMMIT4res switch (nfsstat4 status) {
          case NFS4_OK:
                  COMMIT4resok   resok4;
          default:
                  void;
         };

   DESCRIPTION

      The COMMIT operation forces or flushes data to stable storage for
      the file specified by the current file handle.  The flushed data
      is that which was previously written with a WRITE operation which
      had the stable field set to UNSTABLE4.

      The offset specifies the position within the file where the flush
      is to begin.  An offset value of 0 (zero) means to flush data
      starting at the beginning of the file.  The count specifies the
      number of bytes of data to flush.  If count is 0 (zero), a flush
      from offset to the end of the file is done.

      The server returns a write verifier upon successful completion of
      the COMMIT.  The write verifier is used by the client to determine
      if the server has restarted or rebooted between the initial
      WRITE(s) and the COMMIT.  The client does this by comparing the
      write verifier returned from the initial writes and the verifier
      returned by the COMMIT procedure.  The server must vary the value
      of the write verifier at each server event or instantiation that
      may lead to a loss of uncommitted data.  Most commonly this occurs
      when the server is rebooted; however, other events at the server
      may result in uncommitted data loss as well.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      The COMMIT procedure is similar in operation and semantics to the
      POSIX fsync(2) system call that synchronizes a file's state with
      the disk (file data and metadata is flushed to disk or stable
      storage). COMMIT performs the same operation for a client,
      flushing any unsynchronized data and metadata on the server to the
      server's disk or stable storage for the specified file.  Like
      fsync(2), it may be that there is some modified data or no
      modified data to synchronize.  The data may have been synchronized
      by the server's normal periodic buffer synchronization activity.
      COMMIT should return NFS4_OK, unless there has been an unexpected
      error.

      COMMIT differs from fsync(2) in that it is possible for the client
      to flush a range of the file (most likely triggered by a buffer-
      reclamation scheme on the client before file has been completely
      written).

      The server implementation of COMMIT is reasonably simple.  If the
      server receives a full file COMMIT request, that is starting at
      offset 0 and count 0, it should do the equivalent of fsync()'ing
      the file.  Otherwise, it should arrange to have the cached data in
      the range specified by offset and count to be flushed to stable
      storage.  In both cases, any metadata associated with the file
      must be flushed to stable storage before returning.  It is not an
      error for there to be nothing to flush on the server.  This means
      that the data and metadata that needed to be flushed have already
      been flushed or lost during the last server failure.

      The client implementation of COMMIT is a little more complex.
      There are two reasons for wanting to commit a client buffer to
      stable storage.  The first is that the client wants to reuse a
      buffer.  In this case, the offset and count of the buffer are sent
      to the server in the COMMIT request.  The server then flushes any
      cached data based on the offset and count, and flushes any
      metadata associated with the file.  It then returns the status of
      the flush and the write verifier.  The other reason for the client
      to generate a COMMIT is for a full file flush, such as may be done
      at close.  In this case, the client would gather all of the
      buffers for this file that contain uncommitted data, do the COMMIT
      operation with an offset of 0 and count of 0, and then free all of
      those buffers.  Any other dirty buffers would be sent to the
      server in the normal fashion.

      After a buffer is written by the client with the stable parameter
      set to UNSTABLE4, the buffer must be considered as modified by the
      client until the buffer has either been flushed via a COMMIT
      operation or written via a WRITE operation with stable parameter
      set to FILE_SYNC4 or DATA_SYNC4. This is done to prevent the
      buffer from being freed and reused before the data can be flushed
      to stable storage on the server.

      When a response is returned from either a WRITE or a COMMIT
      operation and it contains a write verifier that is different than
      previously returned by the server, the client will need to
      retransmit all of the buffers containing uncommitted cached data
      to the server.  How this is to be done is up to the implementor.
      If there is only one buffer of interest, then it should probably
      be sent back over in a WRITE request with the appropriate stable
      parameter.  If there is more than one buffer, it might be
      worthwhile retransmitting all of the buffers in WRITE requests
      with the stable parameter set to UNSTABLE4 and then retransmitting
      the COMMIT operation to flush all of the data on the server to
      stable storage.  The timing of these retransmissions is left to
      the implementor.

      The above description applies to page-cache-based systems as well
      as buffer-cache-based systems.  In those systems, the virtual
      memory system will need to be modified instead of the buffer
      cache.

   ERRORS

         NFS4ERR_ACCES
         NFS4ERR_BADHANDLE
         NFS4ERR_FHEXPIRED
         NFS4ERR_IO

         NFS4ERR_ISDIR
         NFS4ERR_LOCKED
         NFS4ERR_MOVED
         NFS4ERR_NOFILEHANDLE
         NFS4ERR_RESOURCE
         NFS4ERR_ROFS
         NFS4ERR_SERVERFAULT
         NFS4ERR_STALE
         NFS4ERR_WRONGSEC

14.2.4.  Operation 6: CREATE - Create a Non-Regular File Object

   SYNOPSIS

         (cfh), name, type -> (cfh), change_info

   ARGUMENT

         union createtype4 switch (nfs_ftype4 type) {
          case NF4LNK:
                  linktext4      linkdata;
          case NF4BLK:
          case NF4CHR:
                  specdata4      devdata;
          case NF4SOCK:
          case NF4FIFO:
          case NF4DIR:
                  void;
         };

         struct CREATE4args {
                 /* CURRENT_FH: directory for creation */
                 component4      objname;
                 createtype4     objtype;
         };

   RESULT

         struct CREATE4resok {
                 change_info4     cinfo;
         };

         union CREATE4res switch (nfsstat4 status) {
          case NFS4_OK:
                  CREATE4resok resok4;
          default:
                  void;
         };

   DESCRIPTION

      The CREATE operation creates a non-regular file object in a
      directory with a given name.  The OPEN procedure MUST be used to
      create a regular file.

      The objname specifies the name for the new object.  If the objname
      has a length of 0 (zero), the error NFS4ERR_INVAL will be
      returned.  The objtype determines the type of object to be
      created: directory, symlink, etc.

      If an object of the same name already exists in the directory, the
      server will return the error NFS4ERR_EXIST.

      For the directory where the new file object was created, 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 file object creation.

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

      The current filehandle is replaced by that of the new object.

   IMPLEMENTATION

      If the client desires to set attribute values after the create, a
      SETATTR operation can be added to the COMPOUND request so that the
      appropriate attributes will be set.

   ERRORS

         NFS4ERR_ACCES
         NFS4ERR_BADHANDLE
         NFS4ERR_BADTYPE
         NFS4ERR_DQUOT
         NFS4ERR_EXIST
         NFS4ERR_FHEXPIRED
         NFS4ERR_INVAL
         NFS4ERR_IO
         NFS4ERR_MOVED
         NFS4ERR_NAMETOOLONG
         NFS4ERR_NOFILEHANDLE
         NFS4ERR_NOSPC
         NFS4ERR_NOTDIR
         NFS4ERR_NOTSUPP

         NFS4ERR_RESOURCE
         NFS4ERR_ROFS
         NFS4ERR_SERVERFAULT
         NFS4ERR_STALE
         NFS4ERR_WRONGSEC

14.2.5.  Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery

   SYNOPSIS

         clientid ->

   ARGUMENT

         struct DELEGPURGE4args {
                 clientid4       clientid;
        };

   RESULT

         struct DELEGPURGE4res {
                 nfsstat4        status;
         };

   DESCRIPTION

      Purges all of the delegations awaiting recovery for a given
      client.  This is useful for clients which do not commit delegation
      information to stable storage to indicate that conflicting
      requests need not be delayed by the server awaiting recovery of
      delegation information.

      This operation should be used by clients that record delegation
      information on stable storage on the client.  In this case,
      DELEGPURGE should be issued immediately after doing delegation
      recovery on all delegations know to the client.  Doing so will
      notify the server that no additional delegations for the client
      will be recovered allowing it to free resources, and avoid
      delaying other clients who make requests that conflict with the
      unrecovered delegations.  The set of delegations known to the
      server and the client may be different.  The reason for this is
      that a client may fail after making a request which resulted in
      delegation but before it received the results and committed them
      to the client's stable storage.

   ERRORS

      NFS4ERR_RESOURCE

      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE_CLIENTID

14.2.6.  Operation 8: DELEGRETURN - Return Delegation

   SYNOPSIS

         stateid ->

   ARGUMENT

         struct DELEGRETURN4args {
                 stateid4        stateid;
         };

   RESULT

         struct DELEGRETURN4res {
                 nfsstat4        status;
         };

   DESCRIPTION

      Returns the delegation represented by the given stateid.

   ERRORS

         NFS4ERR_BAD_STATEID
         NFS4ERR_OLD_STATEID
         NFS4ERR_RESOURCE
         NFS4ERR_SERVERFAULT
         NFS4ERR_STALE_STATEID

14.2.7.  Operation 9: GETATTR - Get Attributes

   SYNOPSIS

         (cfh), attrbits -> attrbits, attrvals

   ARGUMENT

         struct GETATTR4args {
                 /* CURRENT_FH: directory or file */
                 bitmap4         attr_request;
         };

   RESULT

         struct GETATTR4resok {
                 fattr4          obj_attributes;
         };

         union GETATTR4res switch (nfsstat4 status) {
          case NFS4_OK:
                  GETATTR4resok  resok4;
          default:
                  void;
         };

   DESCRIPTION

      The GETATTR operation will obtain attributes for the file system
      object specified by the current filehandle.  The client sets a bit
      in the bitmap argument for each attribute value that it would like
      the server to return.  The server returns an attribute bitmap that
      indicates the attribute values for which it was able to return,
      followed by the attribute values ordered lowest attribute number
      first.

      The server must return a value for each attribute that the client
      requests if the attribute is supported by the server.  If the
      server does not support an attribute or cannot approximate a
      useful value then it must not return the attribute value and must
      not set the attribute bit in the result bitmap.  The server must
      return an error if it supports an attribute but cannot obtain its
      value.  In that case no attribute values will be returned.

      All servers must support the mandatory attributes as specified in
      the section "File Attributes".

      On success, the current filehandle retains its value.

   IMPLEMENTATION

   ERRORS

         NFS4ERR_ACCES
         NFS4ERR_BADHANDLE
         NFS4ERR_DELAY
         NFS4ERR_FHEXPIRED
         NFS4ERR_INVAL
         NFS4ERR_IO
         NFS4ERR_MOVED
         NFS4ERR_NOFILEHANDLE
         NFS4ERR_RESOURCE
         NFS4ERR_SERVERFAULT

         NFS4ERR_STALE
         NFS4ERR_WRONGSEC

14.2.8.  Operation 10: GETFH - Get Current Filehandle

   SYNOPSIS

         (cfh) -> filehandle

   ARGUMENT

         /* CURRENT_FH: */
         void;

   RESULT

         struct GETFH4resok {
                 nfs_fh4         object;
         };

         union GETFH4res switch (nfsstat4 status) {
          case NFS4_OK:
                 GETFH4resok     resok4;
          default:
                 void;
         };

   DESCRIPTION

         This operation returns the current filehandle value.

         On success, the current filehandle retains its value.

   IMPLEMENTATION

      Operations that change the current filehandle like LOOKUP or
      CREATE do not automatically return the new filehandle as a result.
      For instance, if a client needs to lookup a directory entry and
      obtain its filehandle then the following request is needed.

               PUTFH  (directory filehandle)
               LOOKUP (entry name)
               GETFH

   ERRORS

      NFS4ERR_BADHANDLE
      NFS4ERR_FHEXPIRED

      NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_WRONGSEC

14.2.9.  Operation 11: LINK - Create Link to a File

   SYNOPSIS

      (sfh), (cfh), newname -> (cfh), change_info

   ARGUMENT

      struct LINK4args {
              /* SAVED_FH: source object */
              /* CURRENT_FH: target directory */
              component4      newname;
      };

   RESULT

      struct LINK4resok {
              change_info4    cinfo;
      };

      union LINK4res switch (nfsstat4 status) {
       case NFS4_OK:
               LINK4resok resok4;
       default:
               void;
      };

   DESCRIPTION

      The LINK operation creates an additional newname for the file
      represented by the saved filehandle, as set by the SAVEFH
      operation, in the directory represented by the current filehandle.
      The existing file and the target directory must reside within the
      same file system on the server.  On success, the current
      filehandle will continue to be the target directory.

      For the target directory, 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 link
      creation.

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

   IMPLEMENTATION

      Changes to any property of the "hard" linked files are reflected
      in all of the linked files.  When a link is made to a file, the
      attributes for the file should have a value for numlinks that is
      one greater than the value before the LINK operation.

      The comments under RENAME regarding object and target residing on
      the same file system apply here as well. The comments regarding
      the target name applies as well.

      Note that symbolic links are created with the CREATE operation.

   ERRORS

      NFS4ERR_ACCES NFS4ERR_BADHANDLE NFS4ERR_DELAY NFS4ERR_DQUOT
      NFS4ERR_EXIST NFS4ERR_FHEXPIRED NFS4ERR_INVAL NFS4ERR_IO
      NFS4ERR_ISDIR NFS4ERR_MLINK NFS4ERR_MOVED NFS4ERR_NAMETOOLONG
      NFS4ERR_NOFILEHANDLE NFS4ERR_NOSPC NFS4ERR_NOTDIR NFS4ERR_NOTSUPP
      NFS4ERR_RESOURCE NFS4ERR_ROFS NFS4ERR_SERVERFAULT NFS4ERR_STALE
      NFS4ERR_WRONGSEC NFS4ERR_XDEV

14.2.10.  Operation 12: LOCK - Create Lock

   SYNOPSIS

      (cfh) type, seqid, reclaim, stateid, offset, length -> stateid,
      access

   ARGUMENT

      enum nfs4_lock_type {
              READ_LT         = 1,
              WRITE_LT        = 2,
              READW_LT        = 3,    /* blocking read */
              WRITEW_LT       = 4     /* blocking write */ };

      struct LOCK4args {
              /* CURRENT_FH: file */
              nfs_lock_type4  locktype;
              seqid4          seqid;
              bool            reclaim;
              stateid4        stateid;
              offset4         offset;

              length4         length; };

   RESULT

      struct LOCK4denied {
              nfs_lockowner4  owner;
              offset4         offset;
              length4         length; };

      union LOCK4res switch (nfsstat4 status) {
       case NFS4_OK:
               stateid4       stateid;
       case NFS4ERR_DENIED:
               LOCK4denied    denied;
       default:
               void; };

   DESCRIPTION

      The LOCK operation requests a record lock for the byte range
      specified by the offset and length parameters.  The lock type is
      also specified to be one of the nfs4_lock_types.  If this is a
      reclaim request, the reclaim parameter will be TRUE;

      Bytes in a file may be locked even if those bytes are not
      currently allocated to the file.  To lock the file from a specific
      offset through the end-of-file (no matter how long the file
      actually is) use a length field with all bits set to 1 (one).  To
      lock the entire file, use an offset of 0 (zero) and a length with
      all bits set to 1.  A length of 0 is reserved and should not be
      used.

      In the case that the lock is denied, the owner, offset, and length
      of a conflicting lock are returned.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      If the server is unable to determine the exact offset and length
      of the conflicting lock, the same offset and length that were
      provided in the arguments should be returned in the denied
      results.  The File Locking section contains a full description of
      this and the other file locking operations.

   ERRORS

      NFS4ERR_ACCES NFS4ERR_BADHANDLE NFS4ERR_BAD_SEQID

      NFS4ERR_BAD_STATEID NFS4ERR_DELAY NFS4ERR_DENIED NFS4ERR_EXPIRED
      NFS4ERR_FHEXPIRED NFS4ERR_GRACE NFS4ERR_INVAL NFS4ERR_ISDIR
      NFS4ERR_LEASE_MOVED NFS4ERR_LOCK_RANGE NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE NFS4ERR_OLD_STATEID NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT NFS4ERR_STALE NFS4ERR_STALE_CLIENTID
      NFS4ERR_STALE_STATEID NFS4ERR_WRONGSEC

14.2.11.  Operation 13: LOCKT - Test For Lock

   SYNOPSIS

      (cfh) type, owner, offset, length -> {void, NFS4ERR_DENIED ->
      owner}

   ARGUMENT

      struct LOCKT4args {
              /* CURRENT_FH: file */
              nfs_lock_type4  locktype;
              nfs_lockowner4  owner;
              offset4         offset;
              length4         length; };

   RESULT

      union LOCKT4res switch (nfsstat4 status) {
       case NFS4ERR_DENIED:
               LOCK4denied    denied;
       case NFS4_OK:
               void;
       default:
               void; };

   DESCRIPTION

      The LOCKT operation tests the lock as specified in the arguments.
      If a conflicting lock exists, the owner, offset, and length of the
      conflicting lock are returned; if no lock is held, nothing other
      than NFS4_OK is returned.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      If the server is unable to determine the exact offset and length
      of the conflicting lock, the same offset and length that were
      provided in the arguments should be returned in the denied

      results.  The File Locking section contains further discussion of
      the file locking mechanisms.

      LOCKT uses nfs_lockowner4 instead of a stateid4, as LOCK does, to
      identify the owner so that the client does not have to open the
      file to test for the existence of a lock.

   ERRORS

      NFS4ERR_ACCES
      NFS4ERR_BADHANDLE
      NFS4ERR_DELAY
      NFS4ERR_DENIED
      NFS4ERR_FHEXPIRED
      NFS4ERR_GRACE
      NFS4ERR_INVAL
      NFS4ERR_ISDIR
      NFS4ERR_LEASE_MOVED
      NFS4ERR_LOCK_RANGE
      NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_STALE_CLIENTID
      NFS4ERR_WRONGSEC

14.2.12.  Operation 14: LOCKU - Unlock File

   SYNOPSIS

      (cfh) type, seqid, stateid, offset, length -> stateid

   ARGUMENT

      struct LOCKU4args {
              /* CURRENT_FH: file */
              nfs_lock_type4  locktype;
              seqid4          seqid;
              stateid4        stateid;
              offset4         offset;
              length4         length;
      };

   RESULT

      union LOCKU4res switch (nfsstat4 status) {
       case   NFS4_OK:

               stateid4       stateid;
       default:
               void;
      };

   DESCRIPTION

      The LOCKU operation unlocks the record lock specified by the
      parameters.

      On success, the current filehandle retains its value.

   IMPLEMENTATION

      The File Locking section contains a full description of this and
      the other file locking procedures.

   ERRORS

      NFS4ERR_ACCES
      NFS4ERR_BADHANDLE
      NFS4ERR_BAD_SEQID
      NFS4ERR_BAD_STATEID
      NFS4ERR_EXPIRED
      NFS4ERR_FHEXPIRED
      NFS4ERR_GRACE
      NFS4ERR_INVAL
      NFS4ERR_LOCK_RANGE
      NFS4ERR_LEASE_MOVED
      NFS4ERR_MOVED
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_OLD_STATEID
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_STALE_CLIENTID
      NFS4ERR_STALE_STATEID

14.2.13.  Operation 15: LOOKUP - Lookup Filename

   SYNOPSIS

      (cfh), filenames -> (cfh)

   ARGUMENT

      struct LOOKUP4args {
              /* CURRENT_FH: directory */

              pathname4       path;
      };

   RESULT

      struct LOOKUP4res {
              /* CURRENT_FH: object */
              nfsstat4        status;
      };

   DESCRIPTION

      This operation LOOKUPs or finds a file system object starting from
      the directory specified by the current filehandle.  LOOKUP
      evaluates the pathname contained in the array of names and obtains
      a new current filehandle from the final name.  All but the final
      name in the list must be the names of directories.

      If the pathname cannot be evaluated either because a component
      does not exist or because the client does not have permission to
      evaluate a component of the path, then an error will be returned
      and the current filehandle will be unchanged.

      If the path is a zero length array, if any component does not obey
      the UTF-8 definition, or if any component in the path is of zero
      length, the error NFS4ERR_INVAL will be returned.

   IMPLEMENTATION

      If the client prefers a partial evaluation of the path then a
      sequence of LOOKUP operations can be substituted e.g.

               PUTFH  (directory filehandle)
               LOOKUP "pub" "foo" "bar"
               GETFH

      or, if the client wishes to obtain the intermediate filehandles

               PUTFH  (directory filehandle)
               LOOKUP "pub"
               GETFH
               LOOKUP "foo"
               GETFH
               LOOKUP "bar"
               GETFH

      NFS version 4 servers depart from the semantics of previous NFS
      versions in allowing LOOKUP requests to cross mountpoints on the
      server.  The client can detect a mountpoint crossing by comparing
      the fsid attribute of the directory with the fsid attribute of the
      directory looked up.  If the fsids are different then the new
      directory is a server mountpoint.  Unix clients that detect a
      mountpoint crossing will need to mount the server's filesystem.
      This needs to be done to maintain the file object identity
      checking mechanisms common to Unix clients.

      Servers that limit NFS access to "shares" or "exported"
      filesystems should provide a pseudo-filesystem into which the
      exported filesystems can be integrated, so that clients can browse
      the server's name space.  The clients view of a pseudo filesystem
      will be limited to paths that lead to exported filesystems.

      Note: previous versions of the protocol assigned special semantics
      to the names "." and "..".  NFS version 4 assigns no special
      semantics to these names.  The LOOKUPP operator must be used to
      lookup a parent directory.

      Note that this procedure does not follow symbolic links.  The
      client is responsible for all parsing of filenames including
      filenames that are modified by symbolic links encountered during
      the lookup process.

      If the current file handle supplied is not a directory but a
      symbolic link, the error NFS4ERR_SYMLINK is returned as the error.
      For all other non-directory file types, the error NFS4ERR_NOTDIR
      is returned.

   ERRORS

      NFS4ERR_ACCES
      NFS4ERR_BADHANDLE
      NFS4ERR_FHEXPIRED
      NFS4ERR_INVAL
      NFS4ERR_IO
      NFS4ERR_MOVED
      NFS4ERR_NAMETOOLONG
      NFS4ERR_NOENT
      NFS4ERR_NOFILEHANDLE
      NFS4ERR_NOTDIR
      NFS4ERR_RESOURCE
      NFS4ERR_SERVERFAULT
      NFS4ERR_STALE
      NFS4ERR_SYMLINK
      NFS4ERR_WRONGSEC