Name

NFSPROC3_RENAME - Rename a File or Directory

Call Arguments

 

struct RENAME3args {
    diropargs3 from;
    diropargs3 to;
};

Return Arguments

 

struct RENAME3resok {
    wcc_data fromdir_wcc;
    wcc_data todir_wcc;
};

struct RENAME3resfail {
    wcc_data fromdir_wcc;
    wcc_data todir_wcc;
};

union RENAME3res switch (nfsstat3 status) {
    case NFS3_OK:
        RENAME3resok resok;
    default:
        RENAME3resfail resfail;
};

RPC Procedure Description

 

RENAME3res
NFSPROC3_RENAME(RENAME3args) = 14;

Description

Procedure RENAME renames the file identified by from.name in the directory from.dir, to to.name in the directory to.dir. The operation is required to be atomic to the client. The to.dir and from.dir must reside on the same file system and server (in other words, the fsid fields in the attributes for the directories must be the same).

On entry, the arguments in RENAME3args are:

from

A diropargs3 structure identifying the source (the file system object to be renamed):

from.dir

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

from.name

The name of the entry that identifies the object to be renamed. See General File Name Requirements for more information on file names.

to

A diropargs3 structure identifying the target (the new name of the object):

to.dir

The file handle for the directory to which the object is to be renamed.

to.name

The new name for the object. See General File Name Requirements for more information on file names.

If the directory to.dir already contains an entry with the name to.name the source object must be compatible with the target: either both are non-directories or both are directories and the target must be empty. If compatible, the existing target is removed before the rename occurs. If they are not compatible or if the target is a directory but not empty, the server should return the NFS3ERR_EXIST error.

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

fromdir_wcc

Weak cache consistency data for the directory from.dir.

todir_wcc

Weak cache consistency data for the directory to.dir.

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

fromdir_wcc

Weak cache consistency data for the directory from.dir.

todir_wcc

Weak cache consistency data for the directory to.dir.

Implementation Guidance

If to.dir and from.dir reside on different file systems, the NFS3ERR_XDEV error is returned. Even though the operation is atomic, the status NFS3ERR_MLINK may be returned if the server used a "unlink/link/unlink" sequence internally.

A file handle may or may not become stale on a rename. However, server implementors are strongly encouraged to attempt to keep file handles from becoming stale in this fashion.

On some servers, the filenames "." and ".." are invalid as either from.name or to.name. In addition, neither from.name nor to.name can be an alias for from.dir. These servers will return the NFS3ERR_INVAL error in these cases.

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_EXIST

File exists. The file specified already exists.

NFS3ERR_XDEV

The caller attempted to do a cross-device hard link.

NFS3ERR_NOTDIR

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

NFS3ERR_ISDIR

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

NFS3ERR_INVAL

Invalid argument or unsupported argument for an operation. Two examples are attempting a READLINK on an object other than a symbolic link or attempting to SETATTR a time field on a server that does not support this 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_MLINK

Too many hard links.

NFS3ERR_NAMETOOLONG

The filename in an operation was too long.

NFS3ERR_NOTEMPTY

An attempt was made to remove a directory that was not empty.

NFS3ERR_DQUOT

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

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_NOTSUPP

The operation is not supported.

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.