Tech-invite3GPPspaceIETF RFCsSIP
in Index   Prev   Next

RFC 7530

Network File System (NFS) Version 4 Protocol

Pages: 323
Proposed Standard
Obsoletes:  3530
Updated by:  79318587
Part 12 of 14 – Pages 238 to 264
First   Prev   Next

Top   ToC   RFC7530 - Page 238   prevText

16.12. Operation 14: LOCKU - Unlock File

16.12.1. SYNOPSIS

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

16.12.2. ARGUMENT

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

16.12.3. RESULT

union LOCKU4res switch (nfsstat4 status) { case NFS4_OK: stateid4 lock_stateid; default: void; };


The LOCKU operation unlocks the byte-range lock specified by the parameters. The client may set the locktype field to any value that is legal for the nfs_lock_type4 enumerated type, and the server MUST accept any legal value for locktype. Any legal value for locktype has no effect on the success or failure of the LOCKU operation. The ranges are specified as for LOCK. The NFS4ERR_INVAL and NFS4ERR_BAD_RANGE errors are returned under the same circumstances as for LOCK. On success, the current filehandle retains its value.
Top   ToC   RFC7530 - Page 239


If the area to be unlocked does not correspond exactly to a lock actually held by the lock-owner, the server may return the error NFS4ERR_LOCK_RANGE. This includes the cases where (1) the area is not locked, (2) the area is a sub-range of the area locked, (3) it overlaps the area locked without matching exactly, or (4) the area specified includes multiple locks held by the lock-owner. In all of these cases, allowed by POSIX locking [fcntl] semantics, a client receiving this error should, if it desires support for such operations, simulate the operation using LOCKU on ranges corresponding to locks it actually holds, possibly followed by LOCK requests for the sub-ranges not being unlocked. When a client holds an OPEN_DELEGATE_WRITE delegation, it may choose (see Section 16.10.5) to handle LOCK requests locally. In such a case, LOCKU requests will similarly be handled locally.
Top   ToC   RFC7530 - Page 240

16.13. Operation 15: LOOKUP - Look Up Filename

16.13.1. SYNOPSIS

(cfh), component -> (cfh)

16.13.2. ARGUMENT

struct LOOKUP4args { /* CURRENT_FH: directory */ component4 objname; };

16.13.3. RESULT

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


This operation performs a LOOKUP or finds a file system object using the directory specified by the current filehandle. LOOKUP evaluates the component and if the object exists the current filehandle is replaced with the component's filehandle. If the component cannot be evaluated because either it does not exist or the client does not have permission to evaluate it, then an error will be returned, and the current filehandle will be unchanged. If the component is of zero length, NFS4ERR_INVAL will be returned. The component is also subject to the normal UTF-8, character support, and name checks. See Section 12.7 for further discussion.
Top   ToC   RFC7530 - Page 241


If the client wants to achieve the effect of a multi-component lookup, it may construct a COMPOUND request such as the following (and obtain each filehandle): PUTFH (directory filehandle) LOOKUP "pub" GETFH LOOKUP "foo" GETFH LOOKUP "bar" GETFH NFSv4 servers depart from the semantics of previous NFS versions in allowing LOOKUP requests to cross mount points on the server. The client can detect a mount point 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 mount point. UNIX clients that detect a mount point crossing will need to mount the server's file system. 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" file systems should provide a pseudo-file system into which the exported file systems can be integrated, so that clients can browse the server's namespace. The clients' view of a pseudo-file system will be limited to paths that lead to exported file systems. Note: Previous versions of the protocol assigned special semantics to the names "." and "..". NFSv4 assigns no special semantics to these names. The LOOKUPP operator must be used to look up a parent directory. Note that this operation 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 filehandle supplied is not a directory but a symbolic link, NFS4ERR_SYMLINK is returned as the error. For all other non-directory file types, the error NFS4ERR_NOTDIR is returned.
Top   ToC   RFC7530 - Page 242

16.14. Operation 16: LOOKUPP - Look Up Parent Directory

16.14.1. SYNOPSIS

(cfh) -> (cfh)

16.14.2. ARGUMENT

/* CURRENT_FH: object */ void;

16.14.3. RESULT

struct LOOKUPP4res { /* CURRENT_FH: directory */ nfsstat4 status; };


The current filehandle is assumed to refer to a regular directory or a named attribute directory. LOOKUPP assigns the filehandle for its parent directory to be the current filehandle. If there is no parent directory, an NFS4ERR_NOENT error must be returned. Therefore, NFS4ERR_NOENT will be returned by the server when the current filehandle is at the root or top of the server's file tree.


As for LOOKUP, LOOKUPP will also cross mount points. If the current filehandle is not a directory or named attribute directory, the error NFS4ERR_NOTDIR is returned. If the current filehandle is a named attribute directory that is associated with a file system object via OPENATTR (i.e., not a subdirectory of a named attribute directory), LOOKUPP SHOULD return the filehandle of the associated file system object.
Top   ToC   RFC7530 - Page 243

16.15. Operation 17: NVERIFY - Verify Difference in Attributes

16.15.1. SYNOPSIS

(cfh), fattr -> -

16.15.2. ARGUMENT

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

16.15.3. RESULT

struct NVERIFY4res { nfsstat4 status; };


This operation is used to prefix a sequence of operations to be performed if one or more attributes have changed on some file system object. If all the attributes match, then the error NFS4ERR_SAME must be returned. On success, the current filehandle retains its value.
Top   ToC   RFC7530 - Page 244


This operation is useful as a cache validation operator. If the object to which the attributes belong has changed, then the following operations may obtain new data associated with that object -- for instance, to check if a file has been changed and obtain new data if it has: PUTFH (public) LOOKUP "foobar" NVERIFY attrbits attrs READ 0 32767 In the case that a RECOMMENDED attribute is specified in the NVERIFY operation and the server does not support that attribute for the file system object, the error NFS4ERR_ATTRNOTSUPP is returned to the client. When the attribute rdattr_error or any write-only attribute (e.g., time_modify_set) is specified, the error NFS4ERR_INVAL is returned to the client.
Top   ToC   RFC7530 - Page 245

16.16. Operation 18: OPEN - Open a Regular File

16.16.1. SYNOPSIS

(cfh), seqid, share_access, share_deny, owner, openhow, claim -> (cfh), stateid, cinfo, rflags, attrset, delegation

16.16.2. ARGUMENT

/* * Various definitions for OPEN */ enum createmode4 { UNCHECKED4 = 0, GUARDED4 = 1, EXCLUSIVE4 = 2 }; union createhow4 switch (createmode4 mode) { case UNCHECKED4: case GUARDED4: fattr4 createattrs; case EXCLUSIVE4: verifier4 createverf; }; enum opentype4 { OPEN4_NOCREATE = 0, OPEN4_CREATE = 1 }; union openflag4 switch (opentype4 opentype) { case OPEN4_CREATE: createhow4 how; default: void; };
Top   ToC   RFC7530 - Page 246
   /* Next definitions used for OPEN delegation */
   enum limit_by4 {
           NFS_LIMIT_SIZE          = 1,
           NFS_LIMIT_BLOCKS        = 2
           /* others as needed */

   struct nfs_modified_limit4 {
           uint32_t        num_blocks;
           uint32_t        bytes_per_block;

   union nfs_space_limit4 switch (limit_by4 limitby) {
    /* limit specified as file size */
    case NFS_LIMIT_SIZE:
            uint64_t               filesize;
    /* limit specified by number of blocks */
            nfs_modified_limit4    mod_blocks;

   enum open_delegation_type4 {
           OPEN_DELEGATE_NONE      = 0,
           OPEN_DELEGATE_READ      = 1,
           OPEN_DELEGATE_WRITE     = 2

   enum open_claim_type4 {
           CLAIM_NULL              = 0,
           CLAIM_PREVIOUS          = 1,
           CLAIM_DELEGATE_CUR      = 2,
           CLAIM_DELEGATE_PREV     = 3

   struct open_claim_delegate_cur4 {
           stateid4        delegate_stateid;
           component4      file;
Top   ToC   RFC7530 - Page 247
   union open_claim4 switch (open_claim_type4 claim) {
     * No special rights to file.
     * Ordinary OPEN of the specified file.
    case CLAIM_NULL:
            /* CURRENT_FH: directory */
            component4      file;
     * Right to the file established by an
     * open previous to server reboot.  File
     * identified by filehandle obtained at
     * that time rather than by name.
            /* CURRENT_FH: file being reclaimed */
            open_delegation_type4   delegate_type;

     * Right to file based on a delegation
     * granted by the server.  File is
     * specified by name.
            /* CURRENT_FH: directory */
            open_claim_delegate_cur4        delegate_cur_info;

     * Right to file based on a delegation
     * granted to a previous boot instance
     * of the client.  File is specified by name.
            /* CURRENT_FH: directory */
            component4      file_delegate_prev;

    * OPEN: Open a file, potentially receiving an open delegation
   struct OPEN4args {
           seqid4          seqid;
           uint32_t        share_access;
           uint32_t        share_deny;
           open_owner4     owner;
           openflag4       openhow;
           open_claim4     claim;
Top   ToC   RFC7530 - Page 248

16.16.3. RESULT

struct open_read_delegation4 { stateid4 stateid; /* Stateid for delegation */ bool recall; /* Pre-recalled flag for delegations obtained by reclaim (CLAIM_PREVIOUS) */ nfsace4 permissions; /* Defines users who don't need an ACCESS call to open for read */ }; struct open_write_delegation4 { stateid4 stateid; /* Stateid for delegation */ bool recall; /* Pre-recalled flag for delegations obtained by reclaim (CLAIM_PREVIOUS) */ nfs_space_limit4 space_limit; /* Defines condition that the client must check to determine whether the file needs to be flushed to the server on close */ nfsace4 permissions; /* Defines users who don't need an ACCESS call as part of a delegated open */ }; union open_delegation4 switch (open_delegation_type4 delegation_type) { case OPEN_DELEGATE_NONE: void; case OPEN_DELEGATE_READ: open_read_delegation4 read; case OPEN_DELEGATE_WRITE: open_write_delegation4 write; }; /* * Result flags */
Top   ToC   RFC7530 - Page 249
   /* Client must confirm open */
   const OPEN4_RESULT_CONFIRM      = 0x00000002;
   /* Type of file locking behavior at the server */
   const OPEN4_RESULT_LOCKTYPE_POSIX = 0x00000004;

   struct OPEN4resok {
    stateid4       stateid;      /* Stateid for open */
    change_info4   cinfo;        /* Directory change info */
    uint32_t       rflags;       /* Result flags */
    bitmap4        attrset;      /* attribute set for create */
    open_delegation4 delegation; /* Info on any open
                                    delegation */

   union OPEN4res switch (nfsstat4 status) {
    case NFS4_OK:
            /* CURRENT_FH: opened file */
            OPEN4resok      resok4;

16.16.4. Warning to Client Implementers

OPEN resembles LOOKUP in that it generates a filehandle for the client to use. Unlike LOOKUP, though, OPEN creates server state on the filehandle. In normal circumstances, the client can only release this state with a CLOSE operation. CLOSE uses the current filehandle to determine which file to close. Therefore, the client MUST follow every OPEN operation with a GETFH operation in the same COMPOUND procedure. This will supply the client with the filehandle such that CLOSE can be used appropriately. Simply waiting for the lease on the file to expire is insufficient because the server may maintain the state indefinitely as long as another client does not attempt to make a conflicting access to the same file.


The OPEN operation creates and/or opens a regular file in a directory with the provided name. If the file does not exist at the server and creation is desired, specification of the method of creation is provided by the openhow parameter. The client has the choice of three creation methods: UNCHECKED4, GUARDED4, or EXCLUSIVE4.
Top   ToC   RFC7530 - Page 250
   If the current filehandle is a named attribute directory, OPEN will
   then create or open a named attribute file.  Note that exclusive
   create of a named attribute is not supported.  If the createmode is
   EXCLUSIVE4 and the current filehandle is a named attribute directory,
   the server will return EINVAL.

   UNCHECKED4 means that the file should be created if a file of that
   name does not exist and encountering an existing regular file of that
   name is not an error.  For this type of create, createattrs specifies
   the initial set of attributes for the file.  The set of attributes
   may include any writable attribute valid for regular files.  When an
   UNCHECKED4 create encounters an existing file, the attributes
   specified by createattrs are not used, except that when a size of
   zero is specified, the existing file is truncated.  If GUARDED4 is
   specified, the server checks for the presence of a duplicate object
   by name before performing the create.  If a duplicate exists, an
   error of NFS4ERR_EXIST is returned as the status.  If the object does
   not exist, the request is performed as described for UNCHECKED4.  For
   each of these cases (UNCHECKED4 and GUARDED4), where the operation is
   successful, the server will return to the client an attribute mask
   signifying which attributes were successfully set for the object.

   EXCLUSIVE4 specifies that the server is to follow exclusive creation
   semantics, using the verifier to ensure exclusive creation of the
   target.  The server should check for the presence of a duplicate
   object by name.  If the object does not exist, the server creates the
   object and stores the verifier with the object.  If the object does
   exist and the stored verifier matches the verifier provided by the
   client, the server uses the existing object as the newly created
   object.  If the stored verifier does not match, then an error of
   NFS4ERR_EXIST is returned.  No attributes may be provided in this
   case, since the server may use an attribute of the target object to
   store the verifier.  If the server uses an attribute to store the
   exclusive create verifier, it will signify which attribute was used
   by setting the appropriate bit in the attribute mask that is returned
   in the results.

   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.

   Upon successful creation, the current filehandle is replaced by that
   of the new object.

   The OPEN operation provides for Windows share reservation capability
   with the use of the share_access and share_deny fields of the OPEN
   arguments.  The client specifies at OPEN the required share_access
Top   ToC   RFC7530 - Page 251
   and share_deny modes.  For clients that do not directly support
   SHAREs (i.e., UNIX), the expected deny value is DENY_NONE.  In the
   case that there is an existing share reservation that conflicts with
   the OPEN request, the server returns the error NFS4ERR_SHARE_DENIED.
   For a complete SHARE request, the client must provide values for the
   owner and seqid fields for the OPEN argument.  For additional
   discussion of share semantics, see Section 9.9.

   In the case that the client is recovering state from a server
   failure, the claim field of the OPEN argument is used to signify that
   the request is meant to reclaim state previously held.

   The claim field of the OPEN argument is used to specify the file to
   be opened and the state information that the client claims to
   possess.  There are four basic claim types that cover the various
   situations for an OPEN.  They are as follows:

   CLAIM_NULL:  For the client, this is a new OPEN request, and there is
      no previous state associated with the file for the client.

   CLAIM_PREVIOUS:  The client is claiming basic OPEN state for a file
      that was held previous to a server reboot.  This is generally used
      when a server is returning persistent filehandles; the client may
      not have the filename to reclaim the OPEN.

   CLAIM_DELEGATE_CUR:  The client is claiming a delegation for OPEN as
      granted by the server.  This is generally done as part of
      recalling a delegation.

   CLAIM_DELEGATE_PREV:  The client is claiming a delegation granted to
      a previous client instance.  This claim type is for use after a
      SETCLIENTID_CONFIRM and before the corresponding DELEGPURGE in two
      situations: after a client reboot and after a lease expiration
      that resulted in loss of all lock state.  The server MAY support
      SETCLIENTID_CONFIRM MUST NOT remove the client's delegation state,
      and the server MUST support the DELEGPURGE operation.

   The following errors apply to use of the CLAIM_DELEGATE_PREV claim

   o  NFS4ERR_NOTSUPP is returned if the server does not support this
      claim type.

   o  NFS4ERR_INVAL is returned if the reclaim is done at an
      inappropriate time, e.g., after DELEGPURGE has been done.
Top   ToC   RFC7530 - Page 252
   o  NFS4ERR_BAD_RECLAIM is returned if the other error conditions do
      not apply and the server has no record of the delegation whose
      reclaim is being attempted.

   For OPEN requests whose claim type is other than CLAIM_PREVIOUS
   (i.e., requests other than those devoted to reclaiming opens after a
   server reboot) that reach the server during its grace or lease
   expiration period, the server returns an error of NFS4ERR_GRACE.

   For any OPEN request, the server may return an open delegation, which
   allows further opens and closes to be handled locally on the client
   as described in Section 10.4.  Note that delegation is up to the
   server to decide.  The client should never assume that delegation
   will or will not be granted in a particular instance.  It should
   always be prepared for either case.  A partial exception is the
   reclaim (CLAIM_PREVIOUS) case, in which a delegation type is claimed.
   In this case, delegation will always be granted, although the server
   may specify an immediate recall in the delegation structure.

   The rflags returned by a successful OPEN allow the server to return
   information governing how the open file is to be handled.

   OPEN4_RESULT_CONFIRM indicates that the client MUST execute an
   OPEN_CONFIRM operation before using the open file.
   OPEN4_RESULT_LOCKTYPE_POSIX indicates that the server's file locking
   behavior supports the complete set of POSIX locking techniques
   [fcntl].  From this, the client can choose to manage file locking
   state in such a way as to handle a mismatch of file locking

   If the component is of zero length, NFS4ERR_INVAL will be returned.
   The component is also subject to the normal UTF-8, character support,
   and name checks.  See Section 12.7 for further discussion.

   When an OPEN is done and the specified open-owner already has the
   resulting filehandle open, the result is to "OR" together the new
   share and deny status, together with the existing status.  In this
   case, only a single CLOSE need be done, even though multiple OPENs
   were completed.  When such an OPEN is done, checking of share
   reservations for the new OPEN proceeds normally, with no exception
   for the existing OPEN held by the same owner.  In this case, the
   stateid returned has an "other" field that matches that of the
   previous open, while the seqid field is incremented to reflect the
   changed status due to the new open (Section 9.1.4).
Top   ToC   RFC7530 - Page 253
   If the underlying file system at the server is only accessible in a
   read-only mode and the OPEN request has specified
   return NFS4ERR_ROFS to indicate a read-only file system.

   As with the CREATE operation, the server MUST derive the owner, owner
   ACE, group, or group ACE if any of the four attributes are required
   and supported by the server's file system.  For an OPEN with the
   EXCLUSIVE4 createmode, the server has no choice, since such OPEN
   calls do not include the createattrs field.  Conversely, if
   createattrs is specified and includes owner or group (or
   corresponding ACEs) that the principal in the RPC's credentials does
   not have authorization to create files for, then the server may
   return NFS4ERR_PERM.

   In the case where an OPEN specifies a size of zero (e.g., truncation)
   and the file has named attributes, the named attributes are left as
   is.  They are not removed.


The OPEN operation contains support for EXCLUSIVE4 create. The mechanism is similar to the support in NFSv3 [RFC1813]. As in NFSv3, this mechanism provides reliable exclusive creation. Exclusive create is invoked when the how parameter is EXCLUSIVE4. In this case, the client provides a verifier that can reasonably be expected to be unique. A combination of a client identifier, perhaps the client network address, and a unique number generated by the client, perhaps the RPC transaction identifier, may be appropriate. If the object does not exist, the server creates the object and stores the verifier in stable storage. For file systems that do not provide a mechanism for the storage of arbitrary file attributes, the server may use one or more elements of the object metadata to store the verifier. The verifier must be stored in stable storage to prevent erroneous failure on retransmission of the request. It is assumed that an exclusive create is being performed because exclusive semantics are critical to the application. Because of the expected usage, exclusive create does not rely solely on the normally volatile duplicate request cache for storage of the verifier. The duplicate request cache in volatile storage does not survive a crash and may actually flush on a long network partition, opening failure windows. In the UNIX local file system environment, the expected storage location for the verifier on creation is the metadata (timestamps) of the object. For this reason, an exclusive object create may not include initial attributes because the server would have nowhere to store the verifier.
Top   ToC   RFC7530 - Page 254
   If the server cannot support these exclusive create semantics,
   possibly because of the requirement to commit the verifier to stable
   storage, it should fail the OPEN request with the error

   During an exclusive CREATE request, if the object already exists, the
   server reconstructs the object's verifier and compares it with the
   verifier in the request.  If they match, the server treats the
   request as a success.  The request is presumed to be a duplicate of
   an earlier, successful request for which the reply was lost and that
   the server duplicate request cache mechanism did not detect.  If the
   verifiers do not match, the request is rejected with the status

   Once the client has performed a successful exclusive create, it must
   issue a SETATTR to set the correct object attributes.  Until it does
   so, it should not rely upon any of the object attributes, since the
   server implementation may need to overload object metadata to store
   the verifier.  The subsequent SETATTR must not occur in the same
   COMPOUND request as the OPEN.  This separation will guarantee that
   the exclusive create mechanism will continue to function properly in
   the face of retransmission of the request.

   Use of the GUARDED4 attribute does not provide "exactly-once"
   semantics.  In particular, if a reply is lost and the server does not
   detect the retransmission of the request, the operation can fail with
   NFS4ERR_EXIST, even though the create was performed successfully.
   The client would use this behavior in the case that the application
   has not requested an exclusive create but has asked to have the file
   truncated when the file is opened.  In the case of the client timing
   out and retransmitting the create request, the client can use
   GUARDED4 to prevent a sequence such as create, write, create
   (retransmitted) from occurring.

   For share reservations (see Section 9.9), the client must specify a
   value for share_access that is one of OPEN4_SHARE_ACCESS_READ,
   share_deny, the client must specify one of OPEN4_SHARE_DENY_NONE,
   OPEN4_SHARE_DENY_BOTH.  If the client fails to do this, the server
   must return NFS4ERR_INVAL.

   Based on the share_access value (OPEN4_SHARE_ACCESS_READ,
   should check that the requester has the proper access rights to
   perform the specified operation.  This would generally be the results
   of applying the ACL access rules to the file for the current
   requester.  However, just as with the ACCESS operation, the client
Top   ToC   RFC7530 - Page 255
   should not attempt to second-guess the server's decisions, as access
   rights may change and may be subject to server administrative
   controls outside the ACL framework.  If the requester is not
   authorized to READ or WRITE (depending on the share_access value),
   the server must return NFS4ERR_ACCESS.  Note that since the NFSv4
   protocol does not impose any requirement that READs and WRITEs issued
   for an open file have the same credentials as the OPEN itself, the
   server still must do appropriate access checking on the READs and
   WRITEs themselves.

   If the component provided to OPEN resolves to something other than a
   regular file (or a named attribute), an error will be returned to the
   client.  If it is a directory, NFS4ERR_ISDIR is returned; otherwise,
   NFS4ERR_SYMLINK is returned.  Note that NFS4ERR_SYMLINK is returned
   for both symlinks and for special files of other types; NFS4ERR_INVAL
   would be inappropriate, since the arguments provided by the client
   were correct, and the client cannot necessarily know at the time it
   sent the OPEN that the component would resolve to a non-regular file.

   If the current filehandle is not a directory, the error
   NFS4ERR_NOTDIR will be returned.

   If a COMPOUND contains an OPEN that establishes an
   OPEN_DELEGATE_WRITE delegation, then subsequent GETATTRs normally
   result in a CB_GETATTR being sent to the client holding the
   delegation.  However, in the case in which the OPEN and GETATTR are
   part of the same COMPOUND, the server SHOULD understand that the
   operations are for the same client ID and avoid querying the client,
   which will not be able to respond.  This sequence of OPEN and GETATTR
   SHOULD be understood to be the retrieval of the size and change
   attributes at the time of OPEN.  Further, as explained in
   Section 15.2.5, the client should not construct a COMPOUND that mixes
   operations for different client IDs.
Top   ToC   RFC7530 - Page 256

16.17. Operation 19: OPENATTR - Open Named Attribute Directory

16.17.1. SYNOPSIS

(cfh) createdir -> (cfh)

16.17.2. ARGUMENT

struct OPENATTR4args { /* CURRENT_FH: object */ bool createdir; };

16.17.3. RESULT

struct OPENATTR4res { /* CURRENT_FH: named attr directory */ nfsstat4 status; };


The OPENATTR operation is used to obtain the filehandle of the named attribute directory associated with the current filehandle. The result of the OPENATTR will be a filehandle to an object of type NF4ATTRDIR. From this filehandle, READDIR and LOOKUP operations can be used to obtain filehandles for the various named attributes associated with the original file system object. Filehandles returned within the named attribute directory will have a type of NF4NAMEDATTR. The createdir argument allows the client to signify if a named attribute directory should be created as a result of the OPENATTR operation. Some clients may use the OPENATTR operation with a value of FALSE for createdir to determine if any named attributes exist for the object. If none exist, then NFS4ERR_NOENT will be returned. If createdir has a value of TRUE and no named attribute directory exists, one is created. The creation of a named attribute directory assumes that the server has implemented named attribute support in this fashion and is not required to do so by this definition.


If the server does not support named attributes for the current filehandle, an error of NFS4ERR_NOTSUPP will be returned to the client.
Top   ToC   RFC7530 - Page 257

16.18. Operation 20: OPEN_CONFIRM - Confirm Open

16.18.1. SYNOPSIS

(cfh), seqid, stateid -> stateid

16.18.2. ARGUMENT

struct OPEN_CONFIRM4args { /* CURRENT_FH: opened file */ stateid4 open_stateid; seqid4 seqid; };

16.18.3. RESULT

struct OPEN_CONFIRM4resok { stateid4 open_stateid; }; union OPEN_CONFIRM4res switch (nfsstat4 status) { case NFS4_OK: OPEN_CONFIRM4resok resok4; default: void; };


This operation is used to confirm the sequence id usage for the first time that an open-owner is used by a client. The stateid returned from the OPEN operation is used as the argument for this operation along with the next sequence id for the open-owner. The sequence id passed to the OPEN_CONFIRM must be 1 (one) greater than the seqid passed to the OPEN operation (Section 9.1.4). If the server receives an unexpected sequence id with respect to the original OPEN, then the server assumes that the client will not confirm the original OPEN and all state associated with the original OPEN is released by the server. On success, the current filehandle retains its value.


A given client might generate many open_owner4 data structures for a given client ID. The client will periodically either dispose of its open_owner4s or stop using them for indefinite periods of time. The latter situation is why the NFSv4 protocol does not have an explicit
Top   ToC   RFC7530 - Page 258
   operation to exit an open_owner4: such an operation is of no use in
   that situation.  Instead, to avoid unbounded memory use, the server
   needs to implement a strategy for disposing of open_owner4s that have
   no current open state for any files and have not been used recently.
   The time period used to determine when to dispose of open_owner4s is
   an implementation choice.  The time period should certainly be no
   less than the lease time plus any grace period the server wishes to
   implement beyond a lease time.  The OPEN_CONFIRM operation allows the
   server to safely dispose of unused open_owner4 data structures.

   In the case that a client issues an OPEN operation and the server no
   longer has a record of the open_owner4, the server needs to ensure
   that this is a new OPEN and not a replay or retransmission.

   Servers MUST NOT require confirmation on OPENs that grant delegations
   or are doing reclaim operations.  See Section 9.1.11 for details.
   The server can easily avoid this by noting whether it has disposed of
   one open_owner4 for the given client ID.  If the server does not
   support delegation, it might simply maintain a single bit that notes
   whether any open_owner4 (for any client) has been disposed of.

   The server must hold unconfirmed OPEN state until one of three events
   occurs.  First, the client sends an OPEN_CONFIRM request with the
   appropriate sequence id and stateid within the lease period.  In this
   case, the OPEN state on the server goes to confirmed, and the
   open_owner4 on the server is fully established.

   Second, the client sends another OPEN request with a sequence id that
   is incorrect for the open_owner4 (out of sequence).  In this case,
   the server assumes the second OPEN request is valid and the first one
   is a replay.  The server cancels the OPEN state of the first OPEN
   request, establishes an unconfirmed OPEN state for the second OPEN
   request, and responds to the second OPEN request with an indication
   that an OPEN_CONFIRM is needed.  The process then repeats itself.
   While there is a potential for a denial-of-service attack on the
   client, it is mitigated if the client and server require the use of a
   security flavor based on Kerberos V5 or some other flavor that uses

   What if the server is in the unconfirmed OPEN state for a given
   open_owner4, and it receives an operation on the open_owner4 that has
   a stateid but the operation is not OPEN, or it is OPEN_CONFIRM but
   with the wrong stateid?  Then, even if the seqid is correct, the
   server returns NFS4ERR_BAD_STATEID, because the server assumes the
   operation is a replay: if the server has no established OPEN state,
   then there is no way, for example, a LOCK operation could be valid.
Top   ToC   RFC7530 - Page 259
   Third, neither of the two aforementioned events occurs for the
   open_owner4 within the lease period.  In this case, the OPEN state is
   canceled and disposal of the open_owner4 can occur.
Top   ToC   RFC7530 - Page 260

16.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access

16.19.1. SYNOPSIS

(cfh), stateid, seqid, access, deny -> stateid

16.19.2. ARGUMENT

struct OPEN_DOWNGRADE4args { /* CURRENT_FH: opened file */ stateid4 open_stateid; seqid4 seqid; uint32_t share_access; uint32_t share_deny; };

16.19.3. RESULT

struct OPEN_DOWNGRADE4resok { stateid4 open_stateid; }; union OPEN_DOWNGRADE4res switch (nfsstat4 status) { case NFS4_OK: OPEN_DOWNGRADE4resok resok4; default: void; };
Top   ToC   RFC7530 - Page 261


This operation is used to adjust the share_access and share_deny bits for a given open. This is necessary when a given open-owner opens the same file multiple times with different share_access and share_deny flags. In this situation, a close of one of the opens may change the appropriate share_access and share_deny flags to remove bits associated with opens no longer in effect. The share_access and share_deny bits specified in this operation replace the current ones for the specified open file. The share_access and share_deny bits specified must be exactly equal to the union of the share_access and share_deny bits specified for some subset of the OPENs in effect for the current open-owner on the current file. If that constraint is not respected, the error NFS4ERR_INVAL should be returned. Since share_access and share_deny bits are subsets of those already granted, it is not possible for this request to be denied because of conflicting share reservations. As the OPEN_DOWNGRADE may change a file to be not-open-for-write and a write byte-range lock might be held, the server may have to reject the OPEN_DOWNGRADE with an NFS4ERR_LOCKS_HELD. On success, the current filehandle retains its value.
Top   ToC   RFC7530 - Page 262

16.20. Operation 22: PUTFH - Set Current Filehandle

16.20.1. SYNOPSIS

filehandle -> (cfh)

16.20.2. ARGUMENT

struct PUTFH4args { nfs_fh4 object; };

16.20.3. RESULT

struct PUTFH4res { /* CURRENT_FH: */ nfsstat4 status; };


PUTFH replaces the current filehandle with the filehandle provided as an argument. If the security mechanism used by the requester does not meet the requirements of the filehandle provided to this operation, the server MUST return NFS4ERR_WRONGSEC. See Section for more details on the current filehandle.


PUTFH is commonly used as the first operator in an NFS request to set the context for operations that follow it.
Top   ToC   RFC7530 - Page 263

16.21. Operation 23: PUTPUBFH - Set Public Filehandle

16.21.1. SYNOPSIS

- -> (cfh)

16.21.2. ARGUMENT


16.21.3. RESULT

struct PUTPUBFH4res { /* CURRENT_FH: public fh */ nfsstat4 status; };


PUTPUBFH replaces the current filehandle with the filehandle that represents the public filehandle of the server's namespace. This filehandle may be different from the root filehandle, which may be associated with some other directory on the server. The public filehandle concept was introduced in [RFC2054], [RFC2055], and [RFC2224]. The intent for NFSv4 is that the public filehandle (represented by the PUTPUBFH operation) be used as a method of providing compatibility with the WebNFS server of NFSv2 and NFSv3. The public filehandle and the root filehandle (represented by the PUTROOTFH operation) should be equivalent. If the public and root filehandles are not equivalent, then the public filehandle MUST be a descendant of the root filehandle.
Top   ToC   RFC7530 - Page 264


PUTPUBFH is used as the first operator in an NFS request to set the context for operations that follow it. With the NFSv2 and NFSv3 public filehandle, the client is able to specify whether the pathname provided in the LOOKUP should be evaluated as either an absolute path relative to the server's root or relative to the public filehandle. [RFC2224] contains further discussion of the functionality. With NFSv4, that type of specification is not directly available in the LOOKUP operation. The reason for this is because the component separators needed to specify absolute versus relative are not allowed in NFSv4. Therefore, the client is responsible for constructing its request such that either PUTROOTFH or PUTPUBFH is used to signify absolute or relative evaluation of an NFS URL, respectively. Note that there are warnings mentioned in [RFC2224] with respect to the use of absolute evaluation and the restrictions the server may place on that evaluation with respect to how much of its namespace has been made available. These same warnings apply to NFSv4. It is likely, therefore, that because of server implementation details an NFSv3 absolute public filehandle lookup may behave differently than an NFSv4 absolute resolution. There is a form of security negotiation as described in [RFC2755] that uses the public filehandle as a method of employing the Simple and Protected GSS-API Negotiation Mechanism (SNEGO) [RFC4178]. This method is not available with NFSv4, as filehandles are not overloaded with special meaning and therefore do not provide the same framework as NFSv2 and NFSv3. Clients should therefore use the security negotiation mechanisms described in this RFC.

(next page on part 13)

Next Section