`open_file', `close_file', `get_line', `get_byte', `put_byte', `purge_stdin'
----------------------------------------------------------------------------

open_file("FILENAME"[,"MODE"])
     :: Opens FILENAME for reading.

close_file(NUM)
     :: Closes the file indicated by a descriptor NUM.

get_line([NUM])
     :: Reads a line from the file indicated by a descriptor NUM.

get_byte(NUM)
     :: Reads a byte from the file indicated by a descriptor NUM.

put_byte(NUM)
     :: Writes a byte to the file indicated by a descriptor NUM.

purge_stdin()

purge_stdin()
     :: Clears the buffer for the standard input.

RETURN
     `open_file()' : integer (fild id); `close_file()' : 1;
     `get_line()' : string; `get_byte()', `put_byte()' : integer

FILENAME
     file (path) name

MODE
     string

NUM
     non-negative integer (file descriptor)

   * `open_file()' opens a file.  If MODE is not specified, a file is
     opened for reading.  If MODE is specified, it is used as the mode
     specification for C standard I/O function `fopen()'. For example
     `"w"' requests that the file is truncated to zero length or
     created for writing.  `"a"' requests that the file is opened for
     writing or created if it does not exist.  The stream pointer is
     set at the end of the file.  If successful, it returns a
     non-negative integer as the file descriptor.  Otherwise the system
     error function is called.  Unnecessary files should be closed by
     `close_file()'.

   * `get_line()' reads a line from an opened file and returns the line
     as a string. If no argument is supplied, it reads a line from the
     standard input.

   * `get_byte()' reads a byte from an opened file and returns the it
     as an integer.

   * `put_byte()' writes a byte from an opened file and returns the the
     byte as an integer.

   * A `get_line()' call after reading the end of file returns an
     integer 0.

   * Strings can be converted into internal forms with string
     manipulation functions such as `sub_str()', `eval_str()'.

   * `purge_stdin()' clears the buffer for the standard input.  When a
     function receives a character string from `get_line()', this
     functions should be called in advance in order to avoid an
     incorrect behavior which is caused by the characters already
     exists in the buffer.

     [185] Id = open_file("test");
     0
     [186] get_line(Id);
     12345
     
     [187] get_line(Id);
     67890
     
     [188] get_line(Id);
     0
     [189] type(@@);
     0
     [190] close_file(Id);
     1
     [191] open_file("test");
     1
     [192] get_line(1);
     12345
     
     [193] get_byte(1);
     54                   /* the ASCII code of '6' */
     [194] get_line(1);
     7890                 /* the rest of the last line */
     [195] def test() { return get_line(); }
     [196] def test1() { purge_stdin(); return get_line(); }
     [197] test();
                          /* a remaining newline character has been read */
                          /* returns immediately */
     [198] test1();
     123;                 /* input from a keyboard */
     123;                 /* returned value */
     
     [199]

References
     *Note `eval_str': eval_str, *Note `str_len str_chr sub_str':
     str_len str_chr sub_str.

