INtime SDK Help
CreateRtFile
INtime SDK v7 > About INtime > INtime Kernel > Files > CreateRtFile

Open a file and return a handle for a file object.

RTHANDLE CreateRtFile(
LPSTR lpFileName,
DWORD dwAccessMode,
DWORD dwShareMode,
DWORD dwOpenMode,
DWORD dwAttributesAndFlags);

Parameters

lpFileName
The name of the file or device to be opened or created. You may use either forward or back slashed in the path name. The name is limited to MAX_PATH characters.
dwAccessMode
The requested access to the file or device. Possible values include FILE_MODE_READ_ONLY, FILE_MODE_WRITE_ONLY, or FILE_MODE_READ_WRITE.
dwShareMode
The requested sharing mode of the file or device. Possible values include FILE_SHARE_NONE, FILE_SHARE_READ, FILE_SHARE_WRITE, FILE_SHARE_DELETE and FILE_SHARE_ALL. If this parameter is FILE_SHARE_NONE and CreateRtFile succeeds, the file cannot be opened again until the file object is deleted. You cannot request a sharing mode which conflicts with the requested access mode.
Note: FILE_SHARE_DELETE is ignored in INtime Distributed RTOS.
dwOpenMode
Specifies an action to take on a file which exists or does not exist. For devices other than data files this parameter is usually set to FILE_OPEN_EXISTING. The parameter must be set to one of the following:
FILE_CREATE_ALWAYS Creates a new file, always. If the specified file exists and is writable, the function overwrites the file and the call succeeds. If the path does not exist and is valid, a new file is created and the function succeeds.
FILE_CREATE_NEW Creates a file, only if it does not already exist. If the specified file exists, the function fails and the last error is set to E_FEXIST. If the specified file does not exist and the location path is writable, then a new file is created and function succeeds.
FILE_OPEN_ALWAYS Opens a file, always. If the specified file exists, the function succeeds. If the specified file does not exist, and the location is writable, the file is created and the function succeeds.
FILE_OPEN_EXISTING Opens a file or device, only if it exists. If the specified file does not exist, the function fails and last error is set to E_FNEXIST.
FILE_TRUNCATE_EXISTING Opens a file and truncates it to zero bytes in length, only if it exists. If the specified file does not exist, the function fails and last error is set to E_FNEXIST. The caller must open the file with a writable access mode (WRITE_ONLY or READ_WRITE).
dwAttributesAndFlags
A bitfield representing the file attributes to assign to a file being created by this call, and flags to determine the mode in which the file is to be used. The attributes bits are ignored when an existing file is opened. Bit definitions are as follows:
FILE_ATTR_READONLY File is read-only
FILE_ATTR_HIDDEN File is hidden
FILE_ATTR_SYSTEM File is marked as a system file
FILE_ATTR_ARCHIVE File is marked for archiving
FILE_ATTR_NORMAL File is a normal file (no other attribute bits are set)
FILE_FLAG_ASYNCHRONOUS File is opened for asynchronous operations. See the section Synchronous and asynchronous I/O operations for further details.

Return value

If the function succeeds, the return value is a handle for an open file object. If the function fails, the return value is BAD_RTHANDLE. To get extended information call GetLastRtError().

Status value Meaning
E_FNEXIST The name given does not belong to an existing file.
E_PARAM The file name parameter is NULL, or an invalid value was given for dwAccessMode, dwShareMode or dwOpenMode
E_SPACE The volume is full.
E_PATHNAME_SYNTAX The pathname was not correctly formed of valid characters.
E_FEXIST The file specified already exists and FILE_CREATE_NEW was specified.
E_FACCESS The file is not accessible.
E_IO_HARD An I/O error occurred during the operation

Remarks

When an application is finished using the handle, call DeleteRtFile to close the file object and delete it. This not only frees up the resources associated with the handle but has influence on other things such as the accessibility of the file through sharing, committing the data to the underlying medium and so on. Specifics are described elsewhere in this topic as appropriate.

The only file attributes currently supported on INtime Distributed RTOS are FILE_ATTR_READONLY and FILE_ATTR_HIDDEN.

Directories

A directory cannot be created using CreateRtFile. Therefore to open a directory only the OPEN_EXISTING flags value is valid. Use CreateRtDirectory to create a directory.

Requirements

Versions Defined in Include Link to
INtime 6.0 intime/rt/include/rtbase.h rt.h rt.lib

See Also