CreateFile

CreateFile creates or opens a file and returns a handle that can be used to access the object.

Syntax

Copy

HANDLE CreateFile(
    LPCTSTR lpFileName,
    DWORD DesiredAccess,
    DWORD ShareMode,
    LPSECURITY_ATTRIBUTES lpSecurityAttributes,
    DWORD CreationDisposition,
    DWORD FlagsAndAttributes,
    HANDLE hTemplateFile
);

Parameters

lpFileName

A pointer to a null-terminated string that specifies the name of the object to create or open.

If *lpFileName is a path, the string size limit is 260 characters. This limit is related to how CreateFile parses paths.

The CreateFile API cannot be used to create or open files over a network under eRTOS. The path should point to a file location on the local hard drive.

DesiredAccess

Ignored.

ShareMode

Ignored.

lpSecurityAttributes

Ignored.

CreationDisposition

Specifies which action to take on files that exist, and which action to take when files do not exist. For more information about this parameter, see the Comments section. This parameter must be one of the following values:

Value	Description
CREATE_NEW	Creates a new file. CreateFile fails if the specified file already exists.
CREATE_ALWAYS	Creates a new file it it exists, CreateFile overwrites the file and clears the existing attributes
OPEN_EXISTING	Opens the file. CreateFile fails if the file does not exist. See the Comments section for information on when to use the OPEN_EXISTING flag if using CreateFile for devices, including the console.
OPEN_ALWAYS	Opens the file if it exists. If the file does not exist, CreateFile creates the file as if CreationDisposition were CREATE_NEW.
TRUNCATE_EXISTING	Opens a file and truncates it so that its size is zero bytes, if it exists. If the file does not exist, CreateFile fails, and the last-error code is set to ERROR_FILE_NOT_FOUND.

FlagsAndAttributes

Ignored.

hTemplateFile

Ignored.

Return Value

If the function succeeds, it returns an open handle to the specified file. If the function fails, it returns an INVALID_HANDLE_VALUE.

To get extended error information, call GetLastError

If the specified file exists before the function call and CreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS (even though the function has succeeded). If the file does not exist before the call, GetLastError returns ERROR_SUCCESS..

Remarks

Use RtCloseHandle to close an object handle returned by CreateFile.

Files

When creating a new file, CreateFile sets the file length to zero.

When opening an existing file, CreateFile sets the file length according to the value of CreationDisposition.

Directories

An application cannot create a directory with CreateFile; it must call CreateDirectory to create a directory.

Requirements

Minimum supported version	Header	Library
eRTOS 1.0 SDK	windows.h	rtkrnl.lib