User guide

80 CHAPTER 3. THE LIBRARY
FOR count = 0 TO 2 DO
writef("There %p\ is\are\ %-%n thing%-%ps.*n", count)
outputs:
There are 0 things.
There is 1 thing.
There are 2 things.
The implementation of writef (in sysb/blib.b) is a good example of how a vari-
adic function can be defined.
3.3.1 Streams
BCPL uses st r eam s as a convenient method of obtai ni ng device independent input and
output. All the information needed to process a stream is hel d in a vector called a
stream control block (SCB) whose fields have already been summarized in Section 3.1.
The element buf is either zero or holds the stream’s byte buffer which must have
been allocated using getvec and must be freed using freevec when the stream is
closed. The elements pos and end hold p osi t i ons within the byte buffer, file holds a
file pointer for file streams or -1 for s tr e ams connected to the console. The element
id indicates whether t he stream is for input, output or both and work is private work
space for the action function rdfn, wrfn which are called, repectively, when the byte
buffer becomes empty on reading or full on output. The function endfn is called to
close the stream.
Input is read from the currently selected input stream whose SCB is held in the
global variable cis. For an input stre am, pos holds the position of the next character to
be read, and end points to just pas t the last available character in the buffer. Characters
are read using rdch whose definition is given in figure 3.7. If a character is available in
the buffer it is returned after incrementing pos. Exceptionally, the character carriage
return (CR) is ignored since on some systems, such as Windows, lines are terminated
with carriage retur n and linefeed while on others, such as Linux, only linefeed is used.
If the buffer is exhausted, replenish is called to refill it, r e tu rn i ng TRUE if one or
more character are transferr ed. If replenish fails it returns FALSE with the reason why
in result2. Possible reasons are: -1 indicating end of file, -2 indicating a timeout
has occ ur r ed and -3 meaning input is in polling mode and no character is currently
available . By setting the timeoutact field of the SCB to -1, a t i me out is treated as
end of file.
Whenever possible, the buffer contains the previously read character. This is to
allow for a clean and simple implementation of unrdch whose purpose is to step input
back by one character p osi t i on. Its definition is given in figure 3.8.
Output is sent to the currently selected output stream whose SCB is held in the
global variable cos. The SCB field pos of an output stream holds the position in the
buffer of the next character to be written, and end holds the position just past the end
of the buffer. Characters are written using the function wrch whose definition is given
in figure 3.9. The character ch is cop i ed into the byte buffer and pos incremented. I f
the buffer is ful l , it is e mpt i e d by calling the element wrfn. If wri t i ng fails it return
FALSE, causing wrch to abort.