Sets the file information for the specified file.

To retrieve file information using a file handle, seeGetFileInformationByHandle orGetFileInformationByHandleEx.

Syntax

BOOL SetFileInformationByHandle(  [in] HANDLE                    hFile,  [in] FILE_INFO_BY_HANDLE_CLASS FileInformationClass,  [in] LPVOID                    lpFileInformation,  [in] DWORD                     dwBufferSize);

Parameters

[in] hFile

A handle to the file for which to change information.

This handle must be opened with the appropriate permissions for the requested change. For more information,see the Remarks and Example Code sections.

This handle should not be a pipe handle.

[in] FileInformationClass

AFILE_INFO_BY_HANDLE_CLASS enumerationvalue that specifies the type of information to be changed.

For a table of valid values, see the Remarks section.

[in] lpFileInformation

A pointer to the buffer that contains the information to change for the specified file information class.The structure that this parameter points to corresponds to the class that is specified byFileInformationClass.

For a table of valid structure types, see the Remarks section.

[in] dwBufferSize

The size oflpFileInformation, in bytes.

Return value

Returns nonzero if successful or zero otherwise.

To get extended error information, callGetLastError.

Remarks

Certain file information classes behave slightly differently on different operating system releases. Theseclasses are supported by the underlying drivers, and any information they return is subject to change betweenoperating system releases.

The following table shows the valid file information classes and their corresponding data structure types foruse with this function.

You must specify appropriate access flags when creating the file handle for use withSetFileInformationByHandle. For example, ifthe application is usingFILE_DISPOSITION_INFO withtheDeleteFile member set toTRUE, the file would needDELETE access requested in the call to theCreateFile function. To see an example of this, see theExample Code section. For more information about file permissions, seeFile Security and Access Rights.

If there is a transaction bound to the handle, then the changes made will be transacted for the informationclassesFileBasicInfo,FileRenameInfo,FileAllocationInfo,FileEndOfFileInfo, andFileDispositionInfo. IfFileDispositionInfo is specified,only the delete operation is transacted if aDeleteFileoperation was requested. In this case, if the transaction is not committed before the handle is closed, thedeletion will not occur. For more information about TxF, seeTransactional NTFS (TxF).

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

SMB 3.0 does not support rename of alternate data streams on file shares with continuous availability capability.

Examples

The following C++ example shows how to create a file and mark it for deletion when the handle is closed.

//...  HANDLE hFile = CreateFile( TEXT("tempfile"),                              GENERIC_READ | GENERIC_WRITE | DELETE,                             0 /* exclusive access */,                             NULL,                              CREATE_ALWAYS,                             0,                              NULL);  if (hFile != INVALID_HANDLE_VALUE)   {    FILE_DISPOSITION_INFO fdi;    fdi.DeleteFile = TRUE; // marking for deletion    BOOL fResult = SetFileInformationByHandle( hFile,                                                FileDispositionInfo,                                                &fdi,                                                sizeof(FILE_DISPOSITION_INFO) );    if (fResult)     {      // File will be deleted upon CloseHandle.      _tprintf( TEXT("SetFileInformationByHandle marked tempfile for deletion\n") );      // ...       // Now use the file for whatever temp data storage you need,      // it will automatically be deleted upon CloseHandle or       // application termination.      // ...     }    else     {      _tprintf( TEXT("error %lu:  SetFileInformationByHandle could not mark tempfile for deletion\n"),                 GetLastError() );     }    CloseHandle(hFile);     // At this point, the file is closed and deleted by the system.   }  else    {    _tprintf( TEXT("error %lu:  could not create tempfile\n"),               GetLastError() ); }//...

Requirements

See also

CreateFile

File Management Functions

File Security and Access Rights

Generic Access Rights

GetFileInformationByHandle

GetFileInformationByHandleEx