FILE_RENAME_INFORMATION structure

The FILE_RENAME_INFORMATION structure is used to rename a file.

Syntax


typedef struct _FILE_RENAME_INFORMATION {
  BOOLEAN ReplaceIfExists;
  HANDLE  RootDirectory;
  ULONG   FileNameLength;
  WCHAR   FileName[1];
} FILE_RENAME_INFORMATION, *PFILE_RENAME_INFORMATION;

Members

ReplaceIfExists

Set to TRUE to specify that if a file with the given name already exists, it should be replaced with the given file. Set to FALSE if the rename operation should fail if a file with the given name already exists.

RootDirectory

If the file is not being moved to a different directory, or if the FileName member contains the full pathname, this member is NULL. Otherwise, it is a handle for the root directory under which the file will reside after it is renamed.

FileNameLength

Length, in bytes, of the new name for the file.

FileName

The first character of a wide-character string containing the new name for the file. This is followed in memory by the remainder of the string. If the RootDirectory member is NULL, and the file is being moved to a different directory, this member specifies the full pathname to be assigned to the file. Otherwise, it specifies only the file name or a relative pathname.

Remarks

The FILE_RENAME_INFORMATION structure is used to rename a file. This operation can be performed in either of the following ways:

  • Call FltSetInformationFile or ZwSetInformationFile, passing FileRenameInformation as the value of FileInformationClass and passing a caller-allocated buffer formatted as a FILE_RENAME_INFORMATION structure for the value of FileInformation. The FileHandle parameter specifies the file to be renamed.

  • Create an IRP with major function code IRP_MJ_SET_INFORMATION.

File system minifilters must use FltSetInformationFile, not ZwSetInformationFile, to rename a file.

Renaming a file requires DELETE access to the file so that the directory entry may be removed from the current parent directory, as well as the appropriate access to create the new entry in the new parent directory file.

The file name string in the FileName member must be specified in one of the following forms.

  • A simple file name. (The RootDirectory member is NULL.) In this case, the file is simply renamed within the same directory. That is, the rename operation changes the name of the file but not its location.

  • A fully qualified file name. (The RootDirectory member is NULL.) In this case, the rename operation changes the name and location of the file.

  • A relative file name. In this case, the RootDirectory member contains a handle to the target directory for the rename operation. The file name itself must be a simple file name.

General rules for rename operations:

  • A file or directory can only be renamed within a volume. In other words, a rename operation cannot cause a file or directory to be moved to a different volume.

  • A volume's root directory cannot be renamed.

  • If ReplaceIfExists is set to FALSE, and the target exists, the rename operation will fail.

  • Even if ReplaceIfExists is set to TRUE, the rename operation will still fail if a file with the same name already exists and is a directory, a read-only file, or a currently executing file.

  • A volume's files and directories cannot be renamed if the volume is a read-only volume, such as a CDFS volume or a read-only NTFS volume.

Special rules for renaming open files:

  • A file cannot be renamed if it has any open handles, unless it is only open because of a batch opportunistic lock (oplock) and the batch oplock can be broken immediately.

  • A file cannot be renamed if a file with the same name exists and has open handles (except in the batch-oplock case described earlier).

  • A directory cannot be renamed if it or any of its subdirectories contains a file that has open handles (except in the batch-oplock case described earlier).

Special rules for renaming NTFS data streams:

  • The source handle cannot be opened with FILE_DIRECTORY_FILE.

  • The source handle cannot be a directory opened without either FILE_DIRECTORY_FILE or FILE_NON_DIRECTORY_FILE.

  • The new name for the stream must begin with a colon (:).

  • A data stream can only be renamed within a file. In other words, a rename operation cannot cause a data stream to be moved to a different file.

  • A stream on a directory cannot be renamed to the default data stream.

  • If ReplaceIfExists is set to TRUE, the rename operation will succeed only if a stream with the same name exists and is a zero-length data stream.

  • "Renaming" the default data stream is allowed, but this is not a true rename, because it leaves behind a zero-length default data stream.

The size of the FileInformation buffer passed to ZwSetInformationFile or FltSetInformationFile must be >= sizeof(FILE_RENAME_INFORMATION) plus the size in bytes of the FileName string.

Requirements

Header

Ntifs.h (include Ntifs.h or Fltkernel.h)

See also

FltSetInformationFile
IRP_MJ_SET_INFORMATION
ZwSetInformationFile

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft