# Files and Streams
Files and Streams
# Files and Streams
* * *
**[Text and Binary Streams](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#Text%20and%20Binary%20Streams)· [Byte and Wide Streams](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#Byte%20and%20Wide%20Streams)· [Controlling Streams](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#Controlling%20Streams)· [Stream States](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#Stream%20States)**
* * *
A program communicates with the target environment by reading and writing
**files** (ordered sequences of bytes). A file can
be, for example, a data set that you can read and write repeatedly
(such as a disk file), a stream of bytes generated by a program (such
as a pipeline), or a stream of bytes received from or sent to a peripheral
device (such as the keyboard or display). The latter two are
**interactive files**.
Files are typically the principal means by which to interact with a
program.
You manipulate all these kinds of files in much the same way
-- by calling library functions. You include the standard header
`` to declare most of these functions.
Before you can perform many of the operations on a file, the
file must be
**opened**.
Opening a file associates it with a
**stream**, a data structure within
the Standard C library that glosses over many differences
among files of various kinds.
The library maintains the state of each stream in an object of type
[`FILE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#FILE).
The target environment opens three files prior to
[program startup](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#program%20startup).
You can open a file by calling the library function
[`fopen`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fopen) with
two arguments. The first argument is a
[filename](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#filename), a
[multibyte string](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#multibyte%20string)
that the target environment uses to identify which file you
want to read or write. The second argument is a
[C string](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#C%20string) that specifies:
- whether you intend to read data from the file or write data
to it or both
- whether you intend to generate new contents for the file (or
create a file if it did not previously exist) or leave the existing
contents in place
- whether writes to a file can alter existing contents or should
only append bytes at the end of the file
- whether you want to manipulate a
[text stream](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#text%20stream) or a
[binary stream](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#binary%20stream)
Once the file is successfully opened, you can then determine
whether the stream is
**byte oriented** (a
[byte stream](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#byte%20stream)) or
**wide oriented** (a
[wide stream](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#wide%20stream)).
Wide-oriented streams are supported only with
[Amendment 1](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#Amendment%201).
A stream is initially
**unbound**.
Calling certain functions to operate on the stream makes it byte oriented,
while certain other functions make it wide oriented. Once established,
a stream maintains its orientation until it is closed by a call to
[`fclose`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fclose) or
[`freopen`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#freopen).
## Text and Binary Streams
A
**text stream** consists of one or more
**lines** of text
that can be written to a text-oriented display so that they can
be read. When reading from a text stream, the program reads an
`NL` (newline) at the end of each line.
When writing to a text stream, the program writes an
`NL` to signal the end of a line. To match
differing conventions among target environments for representing text
in files, the library functions can alter the number and representations
of characters transmitted between the program and a text stream.
Thus, positioning within a text stream is limited.
You can obtain the current
[file-position indicator](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#file-position%20indicator)
by calling `fgetpos` or
`ftell`.
You can position a text stream at a position obtained this way,
or at the beginning or end of the stream, by calling
`fsetpos` or
`fseek`.
Any other change of position might well be not supported.
For maximum portability, the program should not write:
- empty files
- `space` characters at the end of a line
- partial lines (by omitting the `NL`
at the end of a file)
- characters other than the printable characters,
`NL`, and `HT` (horizontal tab)
If you follow these rules, the sequence of characters you read
from a text stream (either as byte or multibyte characters)
will match the sequence of characters you wrote to the text stream
when you created the file. Otherwise, the library functions can remove
a file you create if the file is empty when you close it. Or they
can alter or delete characters you write to the file.
A
**binary stream** consists of
one or more bytes of arbitrary information.
You can write the value stored in an arbitrary object
to a (byte-oriented) binary stream and read exactly what was stored
in the object when you wrote it. The library functions do not alter
the bytes you transmit between the program and a binary stream. They
can, however, append an arbitrary number of null bytes to the file
that you write with a binary stream. The program must deal with these
additional null bytes at the end of any binary stream.
Thus, positioning within a binary stream is well defined,
except for positioning relative to the end of the stream.
You can obtain and alter the current
[file-position indicator](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#file-position%20indicator)
the same as for a [text stream](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#text%20stream).
Moreover, the offsets used by
`ftell` and
`fseek`
count bytes from the beginning of the stream (which is byte zero),
so integer arithmetic on these offsets yields predictable results.
## Byte and Wide Streams
A
**byte stream**
treats a file as a sequence of bytes. Within the program,
the stream looks like the same sequence of bytes, except
for the possible alterations described above.
By contrast, a
**wide stream** treats a file as a sequence of
**generalized multibyte characters**,
which can have a broad range of encoding rules.
(Text and binary files are still read and written as described above.)
Within the program, the stream looks like the corresponding sequence of
[wide characters](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#Wide-Character%20Encoding).
Conversions between the two representations occur
within the Standard C library. The conversion rules can, in principle,
be altered by a call to
[`setlocale`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_locale.html#setlocale)
that alters the category
[`LC_CTYPE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_locale.html#LC_CTYPE).
Each wide stream determines its conversion rules
at the time it becomes wide oriented, and retains
these rules even if the category
[`LC_CTYPE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_locale.html#LC_CTYPE)
subsequently changes.
Positioning within a wide stream suffers the same limitations as for
[text streams](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#text%20stream). Moreover, the
[file-position indicator](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#file-position%20indicator)
may well have to deal with a
[state-dependent encoding](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#state-dependent%20encoding).
Typically, it includes both a byte offset within the stream
and an object of type
`mbstate_t`. Thus, the only
reliable way to obtain a file position within a wide stream is by calling
`fgetpos`,
and the only reliable way to restore a position
obtained this way is by calling
`fsetpos`.
## Controlling Streams
[`fopen`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fopen)
returns the address of an object of type
[`FILE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#FILE).
You use this address as the `stream` argument to several library
functions to perform various operations on an open file. For a byte
stream, all input takes place as if each character is read by calling
[`fgetc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fgetc),
and all output takes place as if each character is written by calling
[`fputc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fputc).
For a wide stream (with
[Amendment 1](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#Amendment%201)),
all input takes place as if each character is read by calling
[`fgetwc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#fgetwc),
and all output takes place as if each character is written by calling
[`fputwc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#fputwc).
You can
**close** a file by calling
[`fclose`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fclose),
after which the address of the
[`FILE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#FILE) object is invalid.
A [`FILE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#FILE)
object stores the state of a stream, including:
- an **error indicator** --
set nonzero by a function that encounters a read or write error
- an **end-of-file indicator** --
set nonzero by a function that
encounters the end of the file while reading
- a **file-position indicator** --
specifies the next byte in the stream to read or write,
if the file can support positioning requests
- a [stream state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#Stream%20States) --
specifies whether the stream will accept reads and/or writes and, with
[Amendment 1](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#Amendment%201), whether the stream is
[unbound](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#unbound%20stream),
[byte oriented](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#byte%20oriented), or
[wide oriented](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#wide%20oriented)
- a [conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) --
remembers the state of any partly assembled or generated
[generalized multibyte character](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#generalized%20multibyte%20characters), as well as
any shift state for the sequence of bytes in the file)
- a **file buffer** --
specifies the address and size of an array object
that library functions can use to improve the performance
of read and write operations to the stream
Do not alter any value stored in a
[`FILE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#FILE) object or in
a file buffer that you specify for use with that object.
You cannot copy a
[`FILE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#FILE) object
and portably use the address of the copy
as a `stream` argument to a library function.
## Stream States
The valid states, and state transitions, for a stream are
shown in the diagram.
Each of the circles denotes a stable
state. Each of the lines denotes a transition that can occur as the
result of a function call that operates on the stream. Five groups
of functions can cause state transitions.
Functions in the first three groups are declared in
[``](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html):
- the **byte read functions** --
[`fgetc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fgetc),
[`fgets`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fgets),
[`fread`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fread),
[`fscanf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fscanf),
[`getc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#getc),
[`getchar`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#getchar),
[`gets`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#gets),
[`scanf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#scanf),
[`ungetc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#ungetc),
[`vfscanf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#vfscanf)
(added with [C99](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#C99)), and
[`vscanf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#vscanf)
(added with [C99](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#C99))
- the **byte write functions** --
[`fprintf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fprintf),
[`fputc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fputc),
[`fputs`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fputs),
[`fwrite`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fwrite),
[`printf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#printf),
[`putc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#putc),
[`putchar`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#putchar),
[`puts`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#puts),
[`vfprintf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#vfprintf), and
[`vprintf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#vprintf)
- the **position functions** --
[`fflush`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fflush),
[`fseek`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fseek),
[`fsetpos`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#fsetpos), and
[`rewind`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#rewind)
Functions in the remaining two groups are declared
in ``:
- the **wide read functions** --
[`fgetwc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#fgetwc),
[`fgetws`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#fgetws),
[`fwscanf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#fwscanf),
[`getwc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#getwc),
[`getwchar`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#getwchar),
[`ungetwc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#ungetwc),
[`wscanf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wscanf),
[`vfwscanf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#vfwscanf)
(added with [C99](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#C99)), and
[`vwscanf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#vwscanf)
(added with [C99](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#C99))
- the **wide write functions** --
[`fwprintf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#fwprintf),
[`fputwc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#fputwc),
[`fputws`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#fputws),
[`putwc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#putwc),
[`putwchar`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#putwchar),
[`vfwprintf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#vfwprintf),
[`vwprintf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#vwprintf), and
[`wprintf`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wprintf),
For the stream `s`, the call
`fwide(s, 0)`
is always valid and never causes a change of state. Any other call to
[`fwide`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#fwide), or to any of the five
groups of functions described above, causes the state transition shown
in the state diagram. If no such transition is shown, the function
call is invalid.
The state diagram shows how to establish the orientation of
a stream:
- The call
`fwide(s, -1)`,
or to a byte read or byte write function, establishes the stream as
[byte oriented](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#byte%20oriented).
- The call
`fwide(s, 1)`,
or to a wide read or wide write function, establishes the stream as
[wide oriented](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#wide%20oriented).
The state diagram shows that you must call one of the position
functions between most write and read operations:
- You cannot call a read function if the last operation on the
stream was a write.
- You cannot call a write function if the last operation on the
stream was a read, unless that read operation set the
[end-of-file indicator](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#end-of-file%20indicator).
Finally, the state diagram shows that a position operation never
*decreases* the number of valid function calls that can follow.
* * *
See also the
**[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_c_index.html)**.
*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_crit_pjp.html) © 1992-2006by P.J. Plauger and Jim Brodie. All rights reserved.*
Last Published: Oct 06, 2026
[Previous Topic
Characters](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/c_charset.md) [Next Topic
Formatted Output](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/c_lib_prin.md)