CreateFileW

The CreateFileW function (CreateFile) creates or opens a specified file or device.

Important Note: For console applications, use CreateFile with the appropriate character set for your project (e.g., CreateFileA for ASCII or CreateFileW for Unicode).

Syntax


HANDLE CreateFileW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
);

Parameters

Parameters

  • lpFileName [in]

    The name of the file or device that the function will create or open. For more information, see Remarks.

  • dwDesiredAccess [in]

    The requested access to the file or device. This parameter can be one or more of the file access rights (such as GENERIC_READ, GENERIC_WRITE, or both). This can also be any of the access control flags that are defined in Winnt.h.

    This parameter can be zero, but you must enable SE_TCB_PRIVILEGE in the token of the calling process to do so. For more information, see Trading Access for Information.

  • dwShareMode [in]

    A bitmode that specifies the sharing mode of the file or device. The file or device can be opened in shared mode only if it is accessed using a handle that was obtained through some other thread or process.

    This parameter can be a combination of one of the following values:

    • 0: Exclusive access. The calling process cannot revoke read or write access to the file or device while the current handle is open.
    • FILE_SHARE_READ: Subsequent open requests that request read access to the file or device can be initiated.
    • FILE_SHARE_WRITE: Subsequent open requests that request write access to the file or device can be initiated.
    • FILE_SHARE_DELETE: Subsequent open requests that request delete access to the file or device can be initiated.
  • lpSecurityAttributes [in, optional]

    A pointer to a SECURITY_ATTRIBUTES structure that contains the security descriptor for the file or device. If this parameter is NULL, the file or device is assigned a default security descriptor.

  • dwCreationDisposition [in]

    An action to take if a file that is specified by lpFileName exists or does not exist. This parameter must be one of the following values:

    • CREATE_NEW: Creates a new file. If the file exists, the operation fails with ERROR_ALREADY_EXISTS.
    • CREATE_ALWAYS: Creates a new file. If the file exists, the operation overwrites the file and succeeds.
    • OPEN_EXISTING: Opens the file. If the file does not exist, the operation fails with ERROR_FILE_NOT_FOUND.
    • OPEN_ALWAYS: Opens the file. If the file does not exist, the function creates a new file.
    • TRUNCATE_EXISTING: Opens the file and truncates it so that its size is zero bytes. If the file does not exist, the operation fails with ERROR_FILE_NOT_FOUND.
  • dwFlagsAndAttributes [in]

    The attributes and flags for the file or device. This parameter can include any file attribute flag or file system flag. See File Attributes and File and Directory Management Flags for a list of supported values.

    FILE_ATTRIBUTE_NORMAL is the most commonly used attribute flag, but it is optional. If this flag is specified, the other attributes are ignored. This means that the file is just a regular file.

  • hTemplateFile [in, optional]

    A valid handle to a template file with the GENERIC_READ access right. The current file is created with the same security descriptor, information, and attributes as the template file.

    This parameter is optional. If NULL, the new file or device is not created with any template information.

Return Value

Return Value

If the function succeeds, the return value is a persistent, open handle to the specified file or device. The type of the object indicated by the return value, the access to the object, the sharing mode, and the process handle are specified in the parameters.

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

Remarks

This function is used to create or open files, pipes, mail slots, communications resources, disks, directories, and console buffers.

To get extended error information, call GetLastError.

Note: If you are developing a Universal Windows Platform (UWP) app, use Windows.Storage.StorageFile.OpenAsync and related APIs instead of CreateFile.

See Also