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:

• must have been opened with the FILE_FLAG_ASYNCHRONOUS flag specified
• an ASYNCIO structure must be created and passed to the call

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.

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 the current version of INtime Distributed RTOS supports only a FAT file system with strict 8.3 filename restrictions. This restriction will be removed in a future version.

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.

Other file system calls

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

Current directory system calls

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