Microsoft Learn > MSDN Documentation > Windows > API Reference > File Functions > CreateFileW

CreateFileW function (fileapi.h)

Creates or opens a file or I/O device. Returns a handle that can be used to access the file or device. The returned handle has the GENERIC_READ access right if dwDesiredAccess specifies GENERIC_READ or GENERIC_ALL; otherwise, the handle has 0 access right.

Syntax

HANDLE CreateFileW(

                LPCWSTR lpFileName,

                DWORD dwDesiredAccess,

                DWORD dwShareMode,

                LPSECURITY_ATTRIBUTES lpSecurityAttributes,

                DWORD dwCreationDisposition,

                DWORD dwFlagsAndAttributes,

                HANDLE hTemplateFile

            );

Parameters

Parameter	Description
`lpFileName`	The name of the file or device to be created or opened. For block devices, this is typically a disk extent name, such as \\.\PhysicalDrive0. For logical drives, this is typically a drive letter, such as D:. For the server message block (SMB) file system, the name format is \\Server\Share\File. Possible values for lpFileName include: A relative path An absolute path A Universal Naming Convention (UNC) path A device name For a device, the name must be preceded by `\\.\`.
`dwDesiredAccess`	The requested access to the file or device. This parameter can be one or more of the following values: `GENERIC_READ`: Read access to the file or device. `GENERIC_WRITE`: Write access to the file or device. `GENERIC_EXECUTE`: Execute access to the file or device. `GENERIC_ALL`: All possible access rights. For pipes, the access rights are `GENERIC_READ` and `GENERIC_WRITE`.
`dwShareMode`	A bitmask that specifies the sharing mode of an opening file or device. A complying application should not be affected by the share mode of other threads that are opening the same file or device. Possible values: `0`: Prevents other threads from opening the file or device. `FILE_SHARE_READ`: Prevents other threads from opening the file or device for read access. `FILE_SHARE_WRITE`: Prevents other threads from opening the file or device for write access. `FILE_SHARE_DELETE`: Prevents other threads from deleting the file or device.
`lpSecurityAttributes`	A pointer to a `SECURITY_ATTRIBUTES` structure that contains the security descriptor for the file or device to be created. If this parameter is `NULL`, the file or device gets a default security descriptor.
`dwCreationDisposition`	An action to take if the file either exists or does not exist. This parameter can be one of the following values: `CREATE_NEW`: Creates a new file. If the file exists, the operation fails. `CREATE_ALWAYS`: Creates a new file. If the file exists, the operation overwrites the file. `OPEN_EXISTING`: Opens the file. If the file does not exist, the operation fails. `OPEN_ALWAYS`: Opens the file. If the file does not exist, the operation creates a new file. `TRUNCATE_EXISTING`: Opens the file and truncates it so that it has zero length. If the file does not exist, the operation fails.
`dwFlagsAndAttributes`	A file or device attribute and flags. This parameter can be a combination of the following values: `FILE_ATTRIBUTE_ARCHIVE` `FILE_ATTRIBUTE_ENCRYPTED` `FILE_ATTRIBUTE_HIDDEN` `FILE_ATTRIBUTE_NORMAL` `FILE_ATTRIBUTE_OFFLINE` `FILE_ATTRIBUTE_READONLY` `FILE_ATTRIBUTE_SYSTEM` `FILE_ATTRIBUTE_TEMPORARY` `FILE_FLAG_BACKUP_SEMANTICS` `FILE_FLAG_DELETE_ON_CLOSE` `FILE_FLAG_NO_BUFFERING` `FILE_FLAG_OPEN_NO_RECALL` `FILE_FLAG_OPEN_REPARSE_POINT` `FILE_FLAG_POSIX_SEMANTICS` `FILE_FLAG_SEQUENTIAL_SCAN` `FILE_FLAG_SYNCHRONOUS_IO_ALERT` `FILE_FLAG_SYNCHRONOUS_IO_NONALERT` `FILE_FLAG_WRITE_THROUGH`
`hTemplateFile`	A handle to a template file with the `GENERIC_READ` access right. The caller must have the necessary permissions for this operation. This parameter can be `NULL`.

Return Value

If the function succeeds, the return value is an open handle to the specified file, device, named pipe, mail slot, or communications resource. The handle has the GENERIC_READ access right if dwDesiredAccess specifies GENERIC_READ or GENERIC_ALL; otherwise, the handle has 0 access right.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

To create or open a file, use the CreateFileW function. To open a file for reading or writing, use the CreateFileA function.

For more information on handling files and devices, see File Management.

The CreateFileW function can return a handle to a non-file system device, such as a named pipe, mail slot, or communications resource.

When opening a file, the dwCreationDisposition parameter determines what happens if the file exists or does not exist. The dwShareMode parameter determines if other processes can access the file concurrently.

If you are opening a file for writing, you should typically specify GENERIC_WRITE in dwDesiredAccess. If you want to read and write, specify both GENERIC_READ and GENERIC_WRITE.

The dwFlagsAndAttributes parameter allows you to specify various file attributes and flags, such as whether the file should be encrypted, compressed, or opened for sequential access.

The hTemplateFile parameter can be used to pass attributes to the new file from a template file. This is often used to inherit security attributes or other properties.

Requirements

Minimum supported client	Windows 7
Minimum supported server	Windows Server 2008 R2
Header	`fileapi.h` (include `windows.h`)
Library	`Kernel32.lib`
DLL	`Kernel32.dll`