INtime SDK Help
Files
INtime SDK v7 > About INtime > INtime Kernel > Files
In this topic:

The file object

The file object represents the interface between an application and a data file, or certain devices. Operations on the contents of a file, or operations on a device, are executed via this object. Operations on file metadata (name, attributes, etc.) may also be carried out without an explicit file object.

Access to a file's contents or device is initiated by creating a file object, using the CreateRtFile system call. This establishes an interface to the file or device and may limit the types of operation to be carried out, as well as limit the ability of other files objects being created for the same file or device. A file object must also be created if a new data file is to be established.

The name of an existing data file and its attributes may be discovered or changed, or an existing data file may be deleted without creating a file object.

Synchronous and asynchronous I/O operations

Standard operations on a file are synchronous in nature. That is, the operation is completed before the call which initiated the operation returns.

Certain operations on a file may be asynchronous. In other words the completion of an operation may be handled separately from the initiation of that same operation. Currently this may be applied to ReadRtFile and WriteRtFile. In order to start an asynchronous operation the file:

Note that if the FILE_FLAG_ASYNCHRONOUS flag is not set then any subsequent asynchronous operations on the returned file handle will fail with status E_PARAM. The hMailbox field must be initialized with a handle for a data mailbox. The file location at which the operation is to be performed must also be specified in the structure. Optionally the user can provide a completion function and a user context pointer, or else NULL for both parameters. If values are provided then WaitForRtIo will call the function on completion of the operation.

After the operation has been initiated the call returns. Notification of completion of the operation is indicated by the kernel posting the ASYNCIO structure to the mailbox with the status fields wStatus and cbAmountReturned completed. The user may either receive the message directly or can call WaitForRtIo to wait for completion and to return the status fields.

At any time outstanding asynchronous operations may be canceled by calling CancelRtIo, which cancels all outstanding operations for a particular file. All operations which were canceled are completed with an E_IO_CANCELLED status.

In situations where an I/O request is expected to take a large amount of time, such as a refresh or backup of a large database or a slow communications link, asynchronous I/O is generally a good way to optimize processing efficiency. However, for relatively fast I/O operations, the overhead of processing kernel I/O requests and kernel signals may make asynchronous I/O less beneficial, particularly if many fast I/O operations need to be made. In this case, synchronous I/O would be better.

Note: Asynchronous file operations are supported on INtime Distributed RTOS Version 7.

File operations on media

Certain operations are permitted on data files (but not devices) without first opening them and operating through a file object. Such operations include deleting, renaming, retrieving and setting attributes of files, and searching for them.

Current directory operations

Each process and thread maintains a current directory path variable. This contains the default path used when a file name is specified which is not absolute (not a full path). Any non-absolute filename is first appended to the current directory before passing to the file system for opening.

File names

Note that INtime Distributed RTOS Version 7 supports long filenames.

File names and directory names are delineated by either forward or backward slash: "/" or "\", to be OS agnostic.

The use of drive designation: "C:", is not supported in INtime Distributed RTOS.

INtime for Windows and INtime Distributed RTOS file differences

File permissions are set for a single user. Group and other permissions are replicated from owner.

File object system calls

The following APIs act on a file object to manipulate the contents of a file or perform operations on a device.

To... Use this call...
Open or create a file handle for use with subsequent operations on the file data or metadata CreateRtFile
Close a file and delete the file object created by a previous call to CreateRtFile DeleteRtFile
Close and reopen an existing file object with new access and share mode ReOpenRtFile
Read data from the specified file or device ReadRtFile
Write data to the specified file or device WriteRtFile
Move the file pointer of a file SetRtFilePointer
Set the physical file size to the current position of the file pointer SetEndOfRtFile
Retrieve information about an open file GetRtFileInfoByHandle
Set information about an open file SetRtFileInfoByHandle
Set the create-, modify-, and/or access-times for a file, where supported SetRtFileTime
Retrieve the size of an open file GetRtFileSize
Retrieve the type of an open file GetRtFileType
Wait for the completion of a previously started asynchronous operation and return the results WaitForRtIo
Cancel all outstanding asynchronous operations on an open file CancelRtIo
Cause all of the operating system buffers for an open file to be flushed to the disk medium FlushRtFileBuffers

Other file system calls

The following system calls act on files by name, or on their metadata.

To... Use this call...
Move or rename an existing file or directory (including its contents) MoveRtFile
Delete a file from its medium RemoveRtFile
Retrieve common file attributes of a file GetRtFileAttributes
Set the attributes of a named file SetRtFileAttributes
Create a new directory CreateRtDirectory
Delete an existing empty directory RemoveRtDirectory
Search a directory for files matching a pattern FindFirstRtFile
Continues a file search FindNextRtFile
Close a file search FindRtFileClose

Current directory system calls

The following system calls act on the thread and process current directory.

To... Use this call...
Retrieve the full path and file name of the specified file GetFullRtPathName
Retrieve the process current directory GetCurrentRtDirectory
Set a new process current directory SetCurrentRtDirectory
Retrieve the full path and file name of the specified file GetFullRtThreadPathName
Retrieve the calling thread current directory GetCurrentRtThreadDirectory
Set a new thread current directory SetCurrentRtThreadDirectory
Retrieve the path of the application file. GetRtLoadPath
See Also