zRename

Syntax

#include <zPublics.h>

STATUS zRename(
   Key_t        key,
   Xid_t        xid,
   NINT         srcNameSpace,
   const void  *srcPath,
   NINT         srcMatchAttributes,
   NINT         dstNameSpace,
   const void  *dstPath,
   NINT         renameFlags);

Parameters

key

(IN) Specifies who is renaming the files. If one or both paths are relative pathnames, it also specifies the starting directory for pathname resolution.

xid

(IN) Specifies the transaction to which the operation is bound. If the requested action is not part of a transaction, pass zNILXID.

srcNameSpace

(IN) Specifies the starting namespace for the path parameter. In addition to the normal namespace identifiers (zNSPACE_DOS | zNSPACE_MAC | zNSPACE_UNIX | zNSPACE_LONG | zNSPACE_DATA_STREAM | zNSPACE_EXTENDED_ATTRIBUTE), nameSpace can be augmented by ORing the following mode bits:

• zMODE_UTF8

  The default character set for the path is Unicode. However, by ORing zMODE_UTF8, UTF-8 character strings can be used.

• zMODE_DELETED

  Changes the name scanning to look for deleted files in the salvage system, which effectively purges the file.

• zMODE_LINK

  If the last name in the path is a symbolic link, a junction, or a URL link, the scanning does not follow the link but acts on the link object itself.

srcPath

(IN) Points to the path of the file object to be renamed. If the path is not fully qualified, the key must represent a directory for starting the path parsing. The default character set for the pathname is Unicode unless it is specified by srcNameSpace.

srcMatchAttributes

(IN) Specifies the attributes that the file(s) to be renamed must match (optional) (see Match Attributes Values).

dstNameSpace

(IN) Specifies the starting namespace for the path parameter. In addition to the normal namespace identifiers (zNSPACE_DOS | zNSPACE_MAC | zNSPACE_UNIX | zNSPACE_LONG | zNSPACE_DATA_STREAM | zNSPACE_EXTENDED_ATTRIBUTE), nameSpace can be augmented by ORing the following mode bits:

• zMODE_UTF8

  The default character set for the path is Unicode. However, by ORing zMODE_UTF8, UTF-8 character strings can be used.

• zMODE_LINK

  If the last name in the path is a symbolic link, a junction, or a URL link, the scanning does not follow the link but acts on the link object itself.

dstPath

(IN) Points to the target path and name of the file object to be renamed. This cannot be NULL.Wildcards are allowed in the path string. This path must resolve to a directory file that exists, and it must also contain a leaf (link) name that does not yet exist.The target directory must reside in the same volume as the source directory. The default character set for the pathname is Unicode unless it is specified by dstNameSpace.

renameFlags

(IN) Specifies a bit mask that identifies various modes to the rename function (see also Rename Flags Values):

• zRENAME_ALLOW_RENAMES_TO_MYSELF allows a file to be named to its same place without returning an error.

• zRENAME_THIS_NAME_SPACE_ONLY specifies the source and destination namespaces must be the same.

Return Values

Remarks

The return values indicates that none of the file objects were renamed or that some file objects were renamed while others were not.

If zRENAME_THIS_NAME_SPACE_ONLY is set in renameFlags, zRename renames a single file object (no wildcards allowed) in only the specified srcNameSpace and the file object cannot be moved to a different directory path. The name of the file object remains unchanged in all namespaces other than the specified srcNameSpace.

If zRENAME_THIS_NAME_SPACE_ONLY is not set, zRename is much more flexible. The srcPath and dstPath can include wildcards, and they can be in different directories, provided that they are on the same volume. With wildcards, multiple files objects can be renamed with a single iteration of zRename.The nameSpace identifies the primary namespace for which the destination names apply, but the file objects are renamed in all namespaces on the volume. An appropriate destination name in the other namespaces is generated from dstPath.

zRename can be called to salvage files that have been deleted. When a file is deleted, its name type is changed from zNTYPE_FILE to zNTYPE_DELETED_FILE. zRename can then change the name type back to zNTYPE_FILE, thus making the file reappear in the directory.

See Also

zLink