Name

NFSPROC3_COMMIT - Commit Cached Server Data to Stable Storage

Call Arguments

 

struct COMMIT3args {
    nfs_fh3 file;
    offset3 offset;
    count3 count;
};

Return Arguments

 

struct COMMIT3resok {
    wcc_data file_wcc;
    writeverf3 verf;
};

struct COMMIT3resfail {
    wcc_data file_wcc;
};

union COMMIT3res switch (nfsstat3 status) {
    case NFS3_OK:
        COMMIT3resok resok;
    default:
        COMMIT3resfail resfail;
};

RPC Procedure Description

 

COMMIT3res
NFSPROC3_COMMIT(COMMIT3args) = 21;

Description

Procedure COMMIT forces or flushes to stable storage data that was previously written with a WRITE procedure call with the stable field set to UNSTABLE.

On entry, the arguments in COMMIT3args are:

file

The file handle for the file to which data is to be flushed (committed). This must identify a file system object of type NF3REG.

offset

The position within the file at which the flush is to begin. An offset of zero means to flush data starting at the beginning of the file.

count

The number of bytes of data to flush. If count is zero, a flush from offset to the end-of-file is done.

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

file_wcc

Weak cache consistency data for the file. For a client that requires only the post-operation file attributes, these can be found in file_wcc.after.

verf

This is a cookie that the client can use to determine whether the server has rebooted between a call to WRITE and a subsequent call to COMMIT. This cookie must be consistent during a single boot session and must be unique between instances of the NFS Version 3 protocol server where uncommitted data may be lost.

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

file_wcc

Weak cache consistency data for the file. For a client that requires only the post-write file attributes, these can be found in file_wcc.after. Even though the COMMIT failed, full wcc_data is returned to allow the client to determine whether the file changed on the server between calls to WRITE and COMMIT.

Implementation Guidance

Procedure COMMIT is similar in operation and semantics to the XPG4 fsync() system call that synchronises a file's state with the disk, that is it flushes the file's data and metadata to disk. COMMIT performs the same operation for a client, flushing any unsynchronised data and metadata on the server to the server's disk for the specified file. Like fsync(), it may be that there is some modified data or no modified data to synchronise. The data may have been synchronised by the server's normal periodic buffer synchronisation activity. COMMIT will always return NFS3_OK, unless there has been an unexpected error.

COMMIT differs from fsync() 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 zero and count zero, it should do the equivalent of performing fsync() on the file. Otherwise, it will 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 verf 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 zero and count of zero, and then free all of those buffers. Any other dirty buffers would be sent to the server in the normal fashion.

This implementation will require some modifications to the buffer cache on the client. After a buffer is written with stable set to UNSTABLE, it must be considered as dirty by the client system until it is either flushed via a COMMIT operation or written via a WRITE operation with stable set to FILE_SYNC or DATA_SYNC. 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 comes back from either a WRITE or a COMMIT operation that contains an unexpected verf, 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 flag. If there more than one, it might be worthwhile retransmitting all of the buffers in WRITE requests with stable set to UNSTABLE 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.

See additional comments in tagmref_NFSPROC3_WRITE .

Return Codes

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_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.