Creates, opens, or truncates a file; returns a handle that you can use to access the object.

HANDLE CreateFile(
    LPCTSTR lpFileName,
    DWORD dwDesiredAccess,
    DWORD dwShareMode,
    LPSECURITY_ATTRIBUTES lpSecurityAttributes,
    DWORD dwCreationDisposition,
    DWORD dwFlagsAndAttributes,
    HANDLE hTemplateFile
);

Parameters

lpFileName

Pointer to a null-terminated string that specifies the filename to create or open.

If *lpFileName is a path, there is a default string size limit of MAX_PATH characters.

dwDesiredAccess

Type of access to the object. An application can obtain read-only access, write-only access or read/write access. The following shows possible values for dwDesiredAccess:

GENERIC_READ

Specifies read access to the file. You can read data from the file and move the file pointer. For read/write access, combine with GENERIC_WRITE.

GENERIC_WRITE

Specifies write access to the file. You can write data to the file and move the file pointer. For read/write access, combine with GENERIC_READ.

dwShareMode

The requested sharing mode of the file or device, which can be read, write, both, delete, all of these, or none (refer to the following table). Access requests to attributes or extended attributes are not affected by this flag.
If this parameter is zero and CreateFile succeeds, the file or device cannot be shared and cannot be opened again until the handle to the file or device is closed.
You cannot request a sharing mode that conflicts with the access mode that is specified in an existing request that has an open handle. CreateFile would fail and the GetLastError function would return ERROR_SHARING_VIOLATION.

FILE_SHARE_READ

Enables subsequent open operations on a file or device to request read access.
Otherwise, other processes cannot open the file or device if they request read access.
If this flag is not specified, but the file or device has been opened for read access, the function fails.

FILE_SHARE_WRITE

Enables subsequent open operations on a file or device to request write access.
Otherwise, other processes cannot open the file or device if they request write access.
If this flag is not specified, but the file or device has been opened for write access, the function fails.

FILE_SHARE_DELETE

Enables subsequent open operations on a file or device to request delete access.
Otherwise, other processes cannot open the file or device if they request delete access.
If this flag is not specified, but the file or device has been opened for delete access, the function fails.
Note: Delete access allows both delete and rename operations.

lpSecurityAttributes

Ignored; set to NULL.

dwCreationDisposition

Action to take on files that exist, and on files that do not exist:

CREATE_NEW

Creates a new file. If the specified file already exists, the function fails.

CREATE_ALWAYS

Creates a new file. If the file exists, the function overwrites the file and clears the existing attributes.

OPEN_EXISTING

Opens the file. If the file does not exist, the function fails.

OPEN_ALWAYS

Opens the file, if it exists. If the file does not exist, the function creates the file as if dwCreationDisposition were CREATE_NEW.

TRUNCATE_EXISTING

Opens the file. Once opened, the file truncates to zero bytes. The calling process must open the file with at least GENERIC_WRITE access. If the file does not exist, the function fails.

dwFlagsAndAttributes

Ignored.

hTemplateFile

Ignored.

Return Values

An open handle to specified file

Success. May set the error code (call SetLastError).

ERROR_ALREADY_EXISTS

Success; the specified file existed before the call and dwCreationDisposition was CREATE_ALWAYS or OPEN_ALWAYS.

INVALID_HANDLE_VALUE

Failure.

0 (zero)

The file did not exist before the call.

For extended error information, see GetLastError.

Remarks

Use CloseHandle to close an object handle returned by CreateFile.

Requirements

Note

This function operates in the real-time portion of your application.

See Also

CloseHandle, CreateDirectory, ReadFile, WriteFile, iwin32 API, iwin32 Overview