Home > Documentation > Windows > API Reference > File I/O > CreateFileW

CreateFileW function

The CreateFileW function creates or opens a file or I/O device. 

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. For more information, see the Remarks section of this topic.

dwDesiredAccess

The requested access to the file or device. For a list of valid values, see File Access Permissions. This parameter can be zero, but cannot be both zero and GENERIC_READ or GENERIC_WRITE.

This parameter can be one or more of the following flags:

  • GENERIC_READ: Read access to the file or device. For file objects, the bits corresponding to the GENERIC_READ access mask are the cumulative bit-fields of all other generic access rights for access to the file.
  • GENERIC_WRITE: Write access to the file or device. For file objects, the bits corresponding to the GENERIC_WRITE access mask are the cumulative bit-fields of all other generic access rights for write access to the file.
dwShareMode

Specifies how the file or device is to be shared in subsequent open operations. This parameter can be a combination of one of the following values:

  • 0: Exclusive access. If this parameter is 0 and some other thread has the file open, the function will fail.
  • FILE_SHARE_DELETE: Enables subsequent opening of the file or device for deletion.
  • FILE_SHARE_READ: Enables subsequent opening of the file or device for reading. Otherwise, another thread cannot open the file or device for reading while it is opened.
  • FILE_SHARE_WRITE: Enables subsequent opening of the file or device for writing. Otherwise, another thread cannot open the file or device for writing while it is opened.
lpSecurityAttributes

A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If this parameter is NULL, the handle is not inheritable.

The lpSecurityDescriptor member of the structure specifies the security of the file or directory.

dwCreationDisposition

Specifies the action to take if the file specified by lpFileName already exists or does not exist.

This parameter can be one of the following values:

  • CREATE_NEW: Creates a new file. If the file already exists, the function fails with ERROR_ALREADY_EXISTS.
  • CREATE_ALWAYS: Creates a new file. If the file already exists, the function overwrites the file and sets the existing file's attributes and flags.
  • OPEN_EXISTING: Opens the file. If the specified file does not exist, the function fails with ERROR_FILE_NOT_FOUND.
  • OPEN_ALWAYS: Opens the file. If the specified file does not exist, the function creates a new file, exactly as does when dwCreationDisposition is CREATE_NEW.
  • TRUNCATE_EXISTING: Opens the file and truncates it so that it is with zero length. If the specified file does not exist, the function fails with ERROR_FILE_NOT_FOUND.
dwFlagsAndAttributes

Applies only when creating a new file. This parameter can include flags that specify attributes of the file or device, and modifiers that affect how the function handles the file or device. See File and Directory Attributes for a list of attribute flags.

Use the FILE_ATTRIBUTE_NORMAL or FILE_FLAG_OVERLAPPED flags.

hTemplateFile

A handle to a template file with the GENERIC_READ access right. The template file’s extended attributes (EAs) and disk quota information are copied to the new file.

This parameter can be NULL.

If this parameter is not NULL and the file is being created, the function ignores the template file's security attributes. If you are specifying FILE_FLAG_OPEN_REPARSE_POINT and the file is a symbolic link, hTemplateFile must be NULL.

Return Value

If the function succeeds, the return value is an open handle to the specified file, device, named pipe, or mail slot. The handle has the specified access rights to the file or device. If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The CreateFileW function can return a handle to a different type of object than specified by the dwCreationDisposition parameter. For example, if dwCreationDisposition is OPEN_EXISTING and the file object specified by lpFileName is a symbolic link, CreateFileW returns a handle to the symbolic link itself, not the target of the symbolic link. You can use the GetFinalPathNameByHandle function to get the path to the final target of the symbolic link.

To specify a maximum period of time to wait for the CreateFileW function to retrieve a handle for a file, use the CreateFileTransacted function.

The lpFileName parameter can specify a relative path, an absolute path, or a device name.

The CreateFileW function is the primary function used to create or open files. It provides control over access, sharing, creation, and attributes.

When opening a device, the dwCreationDisposition parameter is typically set to OPEN_EXISTING and the dwShareMode parameter should be set to 0.

See Also