Name

NFSPROC3_SETATTR - Set File Attributes

Call Arguments

 

union sattrguard3 switch (bool check) {
    case TRUE:
        nfstime3 obj_ctime;
    case FALSE:
        void;
};

struct SETATTR3args {
    nfs_fh3 object;
    sattr3 new_attributes;
    sattrguard3 guard;
};

Return Arguments

 

struct SETATTR3resok {
    wcc_data obj_wcc;
};

struct SETATTR3resfail {
    wcc_data obj_wcc;
};

union SETATTR3res switch (nfsstat3 status) {
    case NFS3_OK:
        SETATTR3resok resok;
    default:
        SETATTR3resfail resfail;
};

RPC Procedure Description

 

SETATTR3res
NFSPROC3_SETATTR(SETATTR3args) = 2;

Description

Procedure SETATTR changes one or more of the attributes of a file system object on the server. The new attributes are specified by a sattr3 structure.

On entry, the arguments in SETATTR3args are:

object

The file handle for the object.

new_attributes

A sattr3 structure containing Booleans and enumerations describing the attributes to be set and the new values for those attributes.

guard

A sattrguard3 union:

check

TRUE if the server is to verify that guard.obj_ctime matches the ctime for the object; FALSE otherwise.

A client may request that the server check that the object is in an expected state before performing the SETATTR operation. To do this, it sets the argument guard.check to TRUE and the client passes a time value in guard.obj_ctime. If guard.check is TRUE, the server must compare the value of guard.obj_ctime to the current ctime of the object. If the values are different, the server must preserve the object attributes and must return a status of NFS3ERR_NOT_SYNC. If guard.check is FALSE, the server will not perform this check.

Upon successful return, SETATTR3res.status is NFS3_OK and SETATTR3res.resok contains:

obj_wcc

A wcc_data structure containing the old and new attributes for the object.

Otherwise, SETATTR3res.status contains the error on failure and SETATTR3res.resfail contains the following:

obj_wcc

A wcc_data structure containing the old and new attributes for the object.

Implementation Guidance

The guard.check mechanism allows the client to avoid changing the attributes of an object on the basis of stale attributes. It does not guarantee exactly-once semantics. In particular, if a reply is lost and the server does not detect the retransmission of the request, the procedure can fail with the NFS3ERR_NOT_SYNC error, even though the attribute setting was previously performed successfully. The client can attempt to recover from this error by getting fresh attributes from the server and sending a new SETATTR request using the new ctime. The client can optionally check the attributes to avoid the second SETATTR request if the new attributes show that the attributes have already been set as desired (though it may not have been the issuing client that set the attributes).

The new_attributes.size field is used to request changes to the size of a file. A value of zero causes the file to be truncated, a value less than the current size of the file causes data from new size to the end of the file to be discarded, and a size greater than the current size of the file causes logically zeroed data bytes to be added to the end of the file. Servers are free to implement this using holes or actual zero data bytes. Clients must not make any assumptions regarding a server's implementation of this feature, beyond that the bytes returned will be zeroed. Servers must support extending the file size via SETATTR.

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

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

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

In a heterogeneous environment, it is possible that the server will not be able to support the full range of SETATTR requests. The NFS3ERR_INVAL error may be returned if the server can not store a user ID or group ID in its own representation of user or group IDs, respectively. If the server can only support 32 bit offsets and sizes, a SETATTR request to set the size of a file to larger than can be represented in 32 bits will be rejected with this same error.

Return Codes

NFS3ERR_PERM

Not owner. The caller does not have the correct ownership to perform the requested operation.

NFS3ERR_IO

I/O error. Some sort of hard error occurred when the operation was in progress. This could be a disk error, for example.

NFS3ERR_ACCES

Permission denied. The caller does not have the correct permission to perform the requested operation. Contrast this with NFS3ERR_PERM, which restricts itself to owner permission failures.

NFS3ERR_INVAL

Invalid argument or unsupported argument for an operation.

NFS3ERR_NOSPC

No space left on device. The operation would have caused the server's file system to exceed its limit.

NFS3ERR_ROFS

Read-only file system. A modifying operation was attempted on a read-only file system.

NFS3ERR_DQUOT

Resource (quota) hard limit exceeded. The user's resource limit on the server has been exceeded.

NFS3ERR_NOT_SYNC

An update synchronisation mismatch was detected during a SETATTR operation.

NFS3ERR_STALE

Invalid file handle. The file handle given in the arguments was invalid. The file referred to by that file handle no longer exists or access to it has been revoked.

NFS3ERR_BADHANDLE

Invalid NFS file handle. The file handle failed internal consistency checks.

NFS3ERR_SERVERFAULT

An error occurred on the server, which does not map to any of the valid NFS Version 3 protocol error values. The client should translate this into an appropriate error. Clients based on an XPG system may choose to translate this to EIO.