ZwSetInformationFile

NTSTATUS 
ZwSetInformationFile(

IN HANDLE FileHandle,
OUT PIO_STATUS_BLOCK IoStatusBlock,
IN PVOID FileInformation,
IN ULONG Length,
IN FILE_INFORMATION_CLASS FileInformationClass
);

ZwSetInformationFile changes various kinds of information about a given file object.

Parameters

FileHandle

Is the handle returned by a successful call to ZwCreateFile.

IoStatusBlock

Points to a variable that receives the final completion status and information about the operation.

FileInformation

Points to a buffer or variable containing the information to be set for the file. The contents of FileInformation are defined by the FileInformationClass parameter, described later. Setting any member of the structure in this buffer or variable to zero tells ZwSetInformationFile to leave the current information about the file for that member unchanged.

Length

Specifies the size in bytes of FileInformation, which the caller should set according to the given FileInformationClass.

FileInformationClass

Specifies the type of information to be reset for the file. Device and intermediate drivers, can specify any of the following:

FileInformationClass Value Meaning
FileBasicInformation Change FILE_BASIC_INFORMATION about the file. The caller must have opened the file with the DesiredAccess FILE_WRITE_ATTRIBUTES flag set.
FileDispositionInformation Usually, sets DeleteFile in FILE_DISPOSITION_INFORMATION to TRUE, so the file can be deleted when ZwClose is called to release the last open handle for the file object. The caller must have opened the file with the DesiredAccess DELETE flag set.
FilePositionInformation Change the current FILE_POSITION_INFORMATION for the file. The caller must have opened the file with the DesiredAccess FILE_READ_DATA or FILE_WRITE_DATA flag set and with either of the CreateOptions FILE_SYNCHRONOUS_IO_ALERT or FILE_SYNCHRONOUS_IO_NONALERT.
FileEndOfFileInformation Change the current FILE_END_OF_FILE_INFORMATION for the file: either truncate or extend the amount of valid data in the file by moving the current end-of-file position. The caller must have opened the file with the DesiredAccess FILE_WRITE_DATA flag set.

Return Value

ZwSetInformationFile returns STATUS_SUCCESS or an appropriate error status. It also returns the number of bytes set on the file in the Information member of IoStatusBlock.

Comments

ZwSetInformationFile changes information about a file. It ignores any member of a FILE_XXX_INFORMATION structure that is not supported by a particular device or file system. For example, the FAT file system does not support file-creation times, so ZwSetInformationFile ignores the CreationTime member of the FILE_BASIC_INFORMATION structure when it is called to change basic file information for files on a FAT partition.

A caller that sets FileInformationClass to FileDispositionInformation can pass the FileHandle subsequently to ZwClose but to no other Zw..File routine. On return from ZwSetInformationFile, the file has been marked for deletion. It is a programming error to attempt any subsequent operation on the open file except closing it.

If the the caller sets FileInformationClass to FilePositionInformation and the preceding call to ZwCreateFile set the CreateOptions flag FILE_NO_INTERMEDIATE_BUFFERING, certain restrictions on the input FILE_POSITION_INFORMATION CurrentByteOffset are enforced. See ZwCreateFile for specifics.

If the caller sets FileInformationClass to FileEndOfFileInformation and the input FILE_END_OF_FILE_INFORMATION EndOfFile value specifies an offset beyond the current end-of-file mark, ZwSetInformationFile extends the file and writes pad bytes of zeroes between the old and new end-of-file marks.

Callers of ZwSetInformationFile must be running at IRQL PASSIVE_LEVEL.

See Also

FILE_BASIC_INFORMATION, FILE_DISPOSITION_INFORMATION, FILE_END_OF_FILE_INFORMATION, FILE_POSITION_INFORMATION, ZwCreateFile, ZwQueryInformationFile