[ First ] [ Previous ] [ Next ] [ Last ] [ Manuals ]
Streams
A stream is a logical abstraction that isolates input and output operations from the physical characteristics of terminals and structured storage devices. They provide a mapping between a program's data and the data as actually stored on the external devices. Two forms of mapping are supported, for text streams and for binary streams. See "Text Streams and Binary Streams," for more information.
Streams also provide buffering, which is an abstraction of a file designed to reduce hardware I/O requests. Without buffering, data on an I/O device must be accessed one item at a time. This inefficient I/O processing slows program execution considerably. The stdio.h functions use buffers in primary storage to intercept and collect data as it is written to or read from a file. When a buffer is full its contents are actually written to or read from the file, thereby reducing the number of I/O accesses. A buffer's contents can be sent to the file prematurely by using the fflush() function.
The stdio.h header offers three buffering schemes: unbuffered, block buffered, and line buffered. The setvbuf() function is used to change the buffering scheme of any output stream.
When an output stream is unbuffered, data sent to it are immediately read from or written to the file.
When an output stream is block buffered, data are accumulated in a buffer in primary storage. When full, the buffer's contents are sent to the destination file, the buffer is cleared, and the process is repeated until the stream is closed. Output streams are block buffered by default if the output refers to a file.
A line buffered output stream operates similarly to a block buffered output stream. Data are collected in the buffer, but are sent to the file when the line is completed with a newline character ('\n').
A stream is declared using a pointer to a FILE. There are three FILE pointers that are automatically opened for a program: FILE *stdin, FILE *stdout, and FILE *stderr. The FILE pointers stdin and stdout are the standard input and output files, respectively, for interactive console I/O. The stderr file pointer is the standard error output file, where error messages are written to. The stderr stream is written to the console. The stdin, stdout, stderr streams are line buffered.
For more information on routing stdin, stdout, and stderr to a console window, see the chapter on SIOUX.h for Macintosh and WinSIOUX.h for Windows.
Text Streams and Binary Streams
In a binary stream, there is no transformation of the characters during input or output and what is recorded on the physical device is identical to the program's internal data representation.
A text stream consists of sequence of characters organized into lines, each line terminated by a new-line character. To conform to the host system's convention for representing text on physical devices, characters may have to be added altered or deleted during input and output. Thus, there may not be a one-to-one correspondence between the characters in a stream and those in the external representation. These changes occur automatically as part of the mapping associated with text streams. Of course, the input mapping is the inverse of the output mapping and data that are output and then input through text streams will compare equal with the original data.
In MSL, the text stream mapping affects only the linefeed (LF) character, `\n' and the carriage return (CR) character, `\r'. The semantics of these two control characters are:
\n Moves the current print location to the start of the next line.
\r Moves the current print location to the start of the current line.
where " current print location " is defined as "that location on a display device where the next character output by the fputc function would appear".
The ASCII character set defines the value of LF as 0x0a and CR as 0x0d and these are the values that these characters have when they are part of a program's data. On physical devices in the Macintosh operating system, newline characters are represented by 0x0d and CR as 0x0a; in otherwords, the values are interchanged. To meet this requirement, the MSL C library for the Mac, interchanges these values while writing a file and again while reading so that a text stream will be unchanged by writing to a file and then reading back. MPW chose 0x0a for the newline character in its text file, so, when the MPW switch is on, this interchange of values does not take place. However, if you use this option, you must use the MSL C and C++ libraries that were compiled with this option on.
These versions of the libraries are marked with an N (on 68k) or NL (on PPC), for example ANSI (N/2i) C.68k.Lib or ANSI (NL) C.PPC.Lib. See the notes on the mpwc_newline pragma in the Codewarrior C Compilers Reference.
On Windows, the situation is different. There, lines are terminated with the character pair CR/LF. As a consequence, in the Windows implementation of MSL, when a text stream is written to a file, a single newline character is converted to the character pair CR/LF and the reverse transformation is made during reading.
The library routines that read a file have no means of determmining the mode in which text files were written and thus some assumptions have to be made. On the Mac, it is assumed that the Mac convention is used. Under MPW, it is assumed that the MPW convention is to be used and on Windows, the DOS convention.
[ First ] [ Previous ] [ Next ] [ Last ] [ Manuals ]
Visit the Metrowerks website at: http://www.metrowerks.com
For assistance contact Metrowerks Technical Support at: cw_support@metrowerks.com
Copyright © 2000, Metrowerks Corp. All rights reserved.
Last updated: August 16, 2000