[Top] [Prev] [Next]

bufio - buffered input/output module

include "sys.m"; # for Sys->OREAD, etc.
include "bufio.m";
Iobuf: import Bufio;
bufio:= load Bufio Bufio->PATH;
OREAD:  con Sys->OREAD;
OWRITE: con Sys->OWRITE;
ORDWR:  con Sys->ORDWR;
EOF:    con -1;
ERROR:  con -2;
Iobuf: adt {
 seek:  fn(b: self ref Iobuf, n, where: int)           :int;
 read:  fn(b: self ref Iobuf, a: array of byte, n: int):int;
 write: fn(b: self ref Iobuf, a: array of byte, n: int):int;
 getb:  fn(b: self ref Iobuf)                          :int;
 ungetb:fn(b: self ref Iobuf)                          :int;
 getc:  fn(b: self ref Iobuf)                          :int;
 ungetc:fn(b: self ref Iobuf)                          :int;
 gets:  fn(b: self ref Iobuf, sep: int)             :string;
 gett:  fn(b: self ref Iobuf, sep: string)          :string;
 putb:  fn(b: self ref Iobuf, b: byte)                 :int;
 putc:  fn(b: self ref Iobuf, c: int)                  :int;
 puts:  fn(b: self ref Iobuf, s: string)               :int;
 flush: fn(b: self ref Iobuf): int;
 close: fn(b: self ref Iobuf);
};
open:   fn(name: string,  mode: int)           : ref Iobuf;
create: fn(name: string,  mode, perm: int)     : ref Iobuf;
fopen:  fn(fd: ref Sys->FD, mode: int)         : ref Iobuf;
flush:  fn();

Description

The Bufio module provides an interface for buffered I/O. A buffer is an adt which is created with open, fopen, or create.

open (filename, mode)

The open function takes two parameters, a filename and a mode. The mode must be one of OREAD, OWRITE, or ORDWR (defined to match the corresponding values in the Sys module). Both open and fopen return a ref Iobuf to be used in subsequent calls.

create (filename, mode, perm)

The create function creates a new file or prepares to rewrite an existing file, opens it according to mode (as described for open). It returns an associated file descriptor, and a ref Iobuf to be used in subsequent calls.

fopen (fd, mode)

Buffered I/O on an already open file is made possible using fopen, which takes a file descriptor, fd, as its first argument and an open mode as its second argument. The mode of the file descriptor must be compatible with the mode passed to fopen.

The Bufio module keeps an internal reference to files opened for writing so that they can be flushed before being garbage collected. Flushing all dirty files is done with an explicit call to flush(), usually just before exiting the program.

seek (n, where), read (a, n), and write (a, n)

Each function has parameters analogous to its complement in the Sys module (see seek - change file offset and read, write, stream - read, write, or stream file in Chapter 8).

getb ( )

Read a single byte from the buffered stream and return its value as an int.

ungetb ( )

Put the single byte back into the buffered stream, so that a subsequent getb will read it.

getc ( )

Read a single Unicode character, encoded in UTF, and return its value as an int. (See UTF, Unicode, ASCII - character set and format in Appendix A.)

ungetc ( )

Put the single Unicode character, encoded in UTF, back into the buffered stream so that a subsequent getc will read it.

gets (sepchar)

Read a line up to and including a character specified by sepchar, typically a newline. If none is found, read to the end of the file. The returned string includes the terminating character.

gett (sepstr)

Read characters until one of the characters in sepstr. The returned string includes the separator. If none of the separator characters is found, read to the end of the file.

putb (b), putc (c), and puts (s)

Each function writes its respective argument: a byte (b), a character (c), or a string (s). Text is encoded in UTF.

flush ( )

Write contents of the write buffer to the file. Meaningful only for files opened for writing; has no effect on files opened for reading.

close ( )

Flush remaining data in the buffer; if necessary, close the associated file, and discard buffers associated with the file. After close, no further function calls are allowed on the iobuf adt.

Diagnostics

Calls that return a ref type (open, fopen, gets, and gett) return nil when encountering end of file or errors. When an error occurs, the error string, printable with the %r format, will usually be set as a consequence of an error in the underlying Sys module. The other functions return EOF upon encountering end of file, and ERROR when encountering other errors.

Example

The following code fragment opens the file /net/tcp/0/local and reads a line (including the terminating newline character) from this file to initialize the string variable addr. The file is closed implicitly by discarding (assigning nil to) the only reference to its Iobuf.

lc:= bufio->open("/net/tcp/0/local", bufio->OREAD);     
addr:= lc.gets('\n');     
lc = nil; 

See Also
Introduction to Limbo Modules in Chapter 7

open, create - open/create a file for reading or writing in Chapter 8

read, write, stream - read, write, or stream file in Chapter 8

seek - change file offset in Chapter 8



[Top] [Prev] [Next]

infernosupport@lucent.com
Copyright © 1996,Lucent Technologies, Inc. All rights reserved.