Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3010

NFS version 4 Protocol

Pages: 212
Obsoleted by:  3530
Part 5 of 8 – Pages 102 to 125
First   Prev   Next

ToP   noToC   RFC3010 - Page 102   prevText

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>; ... };
ToP   noToC   RFC3010 - Page 103
      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.
ToP   noToC   RFC3010 - Page 104
      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
ToP   noToC   RFC3010 - Page 105

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.
ToP   noToC   RFC3010 - Page 106
      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.
ToP   noToC   RFC3010 - Page 107
      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
ToP   noToC   RFC3010 - Page 108

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
ToP   noToC   RFC3010 - Page 109
         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.
ToP   noToC   RFC3010 - Page 110
      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.
ToP   noToC   RFC3010 - Page 111
      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
ToP   noToC   RFC3010 - Page 112
         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; };
ToP   noToC   RFC3010 - Page 113
   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
ToP   noToC   RFC3010 - Page 114
         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
ToP   noToC   RFC3010 - Page 115
      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
ToP   noToC   RFC3010 - Page 116
         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
ToP   noToC   RFC3010 - Page 117
         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
ToP   noToC   RFC3010 - Page 118
      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.
ToP   noToC   RFC3010 - Page 119
      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;
ToP   noToC   RFC3010 - Page 120
              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
ToP   noToC   RFC3010 - Page 121
      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
ToP   noToC   RFC3010 - Page 122
      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:
ToP   noToC   RFC3010 - Page 123
               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 */
ToP   noToC   RFC3010 - Page 124
              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
ToP   noToC   RFC3010 - Page 125
      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


(next page on part 6)

Next Section