Routines

The open_file() routine is perhaps the most complicated of all the low level file I/O routines. It takes a filename and some mode flags, opens the file, and returns a handle to the file. A file handle is a platform-specific identifier uniquely identifying the open file. The mode flags specify if the file is to be opened in read-only, write-only, or read-write mode. The flags also specify if the file must previously exist for an open operation to be successful, if the file can be opened whether or not it previously existed, or if the file is truncated (position and end of file marker set to 0) once it is open. If the file is opened successfully, return no_io_error. If there was an error opening the file, return io_error.

The open_temp_file() routine in the file_io_Starter.c file is mostly platform independent. It may be customized if there are more efficient ways to perform the task. The open_temp_file() routine is called by tmpfile() to perform the low level work of creating a new temporary file (which is automatically deleted when closed).

The read_file() routine takes a file handle, a buffer, and the size of the buffer. This function must read information from the file described by the file handle into the buffer. The buffer does not have to be completely filled, but at least one character should be read. The number of characters successfully read is returned in the count parameter. If an end of file is reached after more than one character has been read, simply return the number of characters read. The subsequent call to this function should then store zero in the count argument and a result code of io_EOF. If the read operation succeeds, return no_io_error. If the read fails, return io_error.

The write_file() routine takes a file handle, a buffer, and the size of the buffer. It should then write information to the file described by the file handle from the buffer. The number of characters successfully written is returned in the count parameter. If the write was successful, return no_io_error. If the write failed, return io_error. The position_file() routine takes a file handle, a position displacement, and a positioning mode and should set the current position in the file described by the file handle based on the displacement and mode. The displacement value is passed as a variable of type unsigned long due to certain internal constraints of EWL. The value should actually be treated as type signed long. The mode specifies if displacement is an absolute position in the file (treat as position of 0 + displacement), a change from the current position (treat as current position + displacement), or an offset from the end of file mark (treat as end-of-file position + displacement). If the positioning was successful, return no_io_error. If the positioning failed, return io_error.

The close_file() routine closes the specified file. If the file was created by open_temp_file(), it should additionally be deleted. If the close operation is successful, return no_io_error. If the close failed, return io_error.

The temp_file_name() routine creates a new unique file name suitable for a temporary file. Function tmpnam() uses this function to perform the low-level work.

The delete_file() routine deletes an existing file, given its file name. If the delete operation is successful, return no_io_error. If the delete failed, return io_error.

The rename_file() routine renames an existing file, given its existing file name and a desired new file name. If the rename is successful, return no_io_error. If the rename failed, return io_error.

Finally, if the platform wants to provide some additional nonstandard file I/O routines that are common to the Windows operating system, make sure EWL_WIDE_CHAR is defined as 1, then also define EWL_WFILEIO_AVAILABLE as 1. The following stub routines must also be completed in the file_io_plat.c source file. All routines take wchar_t* parameters instead of char*: wopen_file() (same function as open_file()), wtemp_file_name() (same function as temp_file_name()), wdelete_file() (same function as delete_file()), and wrename_file() (same function as rename_file).