Name

NFSPROC3_REMOVE - Remove a File

Call Arguments

 

struct REMOVE3args {
    diropargs3 object;
};

Return Arguments

 

struct REMOVE3resok {
    wcc_data dir_wcc;
};

struct REMOVE3resfail {
    wcc_data dir_wcc;
};

union REMOVE3res switch (nfsstat3 status) {
    case NFS3_OK:
        REMOVE3resok resok;
    default:
        REMOVE3resfail resfail;
};

RPC Procedure Description

 

REMOVE3res
NFSPROC3_REMOVE(REMOVE3args) = 12;

Description

Procedure REMOVE removes (deletes) an entry from a directory. If the entry in the directory was the last reference to the corresponding file system object, the object may be destroyed.

On entry, the arguments in REMOVE3args are:

object

A diropargs3 structure identifying the entry to be removed:

dir

The file handle for the directory from which the entry is to be removed.

name

The name of the entry to be removed. See General File Name Requirements for more information on file names.

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

dir_wcc

Weak cache consistency data for the directory object.dir. For a client that requires only the post-.IR REMOVE directory attributes, these can be found in dir_wcc.after.

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

dir_wcc

Weak cache consistency data for the directory object.dir. For a client that requires only the post-.IR REMOVE directory attributes, these can be found in dir_wcc.after.

Even though the REMOVE failed, full wcc_data is returned to allow the client to determine whether the failing REMOVE changed the directory.

Implementation Guidance

In general, REMOVE is intended to remove non-directory file objects and RMDIR is to be used to remove directories. However, REMOVE can be used to remove directories, subject to restrictions imposed by either the client or server interfaces. This had been a source of confusion in the NFS Version 2 protocol.

The concept of last reference is server specific. However, if the nlink field in the previous attributes of the object had the value 1, the client should not rely on referring to the object via a file handle. Likewise, the client should not rely on the resources (disk space, directory entry and so on) formerly associated with the object becoming immediately available. Thus, if a client needs to be able to continue to access a file after using REMOVE to remove it, the client must take steps to make sure that the file will still be accessible. The usual mechanism used is to use RENAME to rename the file from its old name to a new hidden name.

See General File Name Requirements for more information on file names.

Return Codes

NFS3ERR_NOENT

No such file or directory. The file or directory name specified does not exist.

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_NOTDIR

Not a directory. The caller specified a non-directory in a directory operation.

NFS3ERR_NAMETOOLONG

The filename in an operation was too long.

NFS3ERR_ROFS

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

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.