The file stream
The file stream provides access to an operating-system file through the stream I/O interface.
To support a data stream on an operating-system file, the DataBlade
API provides
the stream I/O functions in the following table..
| Stream I/O task | Stream I/O function |
|---|---|
| Initialize and open a file stream. | mi_stream_open_fio() |
| Move the file seek position to the desired location. | mi_stream_seek() |
| Read a specified number of bytes from the file stream. | mi_stream_read() |
| Write a specified number of bytes to the file stream. | mi_stream_write() |
| Obtain the current file seek position, returning it from the function. | mi_stream_tell() |
| Obtain the current file seek position, returning it in a function parameter. | mi_stream_getpos() |
| Set the file seek position. | mi_stream_setpos() |
| Obtain the length of the operating-system file. | mi_stream_length() |
| Close the file stream. | mi_stream_close() |
Tip: You can also use the mi_stream_get_error() and mi_stream_eof() functions
on a file stream.
As Table 1 shows, the stream I/O interface for a file stream consists of a type-specific stream-open function, mi_stream_open_fio(), plus the generic stream I/O functions. The mi_stream_open_fio() function opens the file and returns a new file stream.
The other stream I/O functions in Table 1 handle return status differently from DataBlade
API file-access
functions because the stream I/O functions do not allow you to obtain
the errno status value directly. Instead, these
functions handle their return status as follows:
- A file-access function returns MI_OK for success and sets errno to indicate an error, but a stream I/O function
returns the MI_OK status for success and a negative number to indicate
an error.
The stream I/O function maps the values associated with errno to DataBlade API constants that have negative values. The mistream.h header file defines these constants.
- A file-access function returns the amount written to or read from
a file, but a stream I/O function returns either of the following
values:
- On success, the amount written or read
- On failure, a negative number (defined in mistream.h)