stream Class Reference


The class stream implements the support of the system streams that one can use for reading and writing to files, named pipes, and standard interprocess  pipes. 

In case of error occuring during the execution of a stream class method, the thread local variable *laststreamerror* will be set to the corresponding system error message, and must be reset to nil after use.

For performance reason, a C structure containing buffers and flags is also bound to the property lfile of each instance of the class. Stream and file functions not implemented in the present class can be called directly with the FFI (see library class) using the file descriptor which can be queried by calling the file-fileno function.

see also the function select and the class file .


  • stream-char-in-buffer
  • stream-clear-input
  • stream-constructor
  • stream-destructor
  • stream-eof
  • stream-fileptr
  • stream-fread
  • stream-fseek
  • stream-ftell
  • stream-fwrite
  • stream-read-char
  • stream-read-char-direct
  • stream-read-string
  • stream-showbin
  • stream-unread-char
  • stream-write-char
  • stream-write-line
  • stream-write-string

  • List of all Inherited Classes

  • file
  • class

  • stream-char-in-buffer

    (char-in-buffer arg1 arg2 )

    Function Type subr
    Arguments a stream object, optional t or nil
    Return Value t or nil
    Description checks if a character has been unread on the stream object; the optional argument sets the charInBuffer state of the stream object to t or nil.
    Example (char-in-buffer stdin) => nil

    stream-clear-input

    (clear-input arg )

    Function Type subr
    Arguments a stream object
    Return Value nil
    Description invalidates the stream object input buffer so that the next stream-read-char, stream-read-line or stream-fread operation must require a real read on the stream descriptor
    Example (clear-input mystream)

    stream-constructor

    (make-instance stream arg1 arg2 arg3 ... argn )

    Function Type subr
    Arguments the symbol stream, a mandatory string, a series of optional keywords some followed by values
    Return Value a stream object
    Description never call stream-constructor directly but always through make-instance ;

    the first argument is mandatory and gives the filename of the stream;

    the rest of the arguments are optional keywords;

    the keyword 'read indicates that the file will be opened in read mode, which is the default mode if the mode is not specified; the keyword 'write specifies write mode and the keyword 'append specifies append mode; if more than one mode keyword is supplied, the last one is used;

    the keyword 'update allows updating the file;

    the keyword 'maxstring followed by an integer gives the size of the input buffer; the default length is the same as that defined by the -t parameter of the interpreter thread, or 4096;

    the keyword 'historysize followed by an integer indicates the length of the keyboard history to be used when the file is a terminal;

    all the keywords must evaluate to the expected symbols or be quoted to prevent evaluation
    Example (make-instance stream "myfile.txt" 'read 'update 'maxstring 2048)

    stream-destructor

    (destroy-instance arg )

    Function Type subr
    Arguments a stream object
    Return Value t
    Description never call stream-destructor directly but always through destroy-instance ; the destructor closes the stream and saves the file if it was created by the constructor
    Example (destroy-instance mystream)

    stream-eof

    (eof arg )

    Function Type subr
    Arguments a stream object
    Return Value t or nil
    Description returns t if the stream has encountered an irrecuperable error or has been closed; returns nil is the stream is still  operable
    Example (eof mystream)

    stream-fileptr

    (fileptr arg )

    Function Type subr
    Arguments a stream object
    Return Value an unsigned integer
    Description returns the value of the FILE pointer to the stream as an unsigned integer
    Example (fileptr stdin) => 0xb7e87300

    stream-fread

    (fread arg1 arg2 arg3 )

    Function Type subr
    Arguments a stream object, a binary, an optional integer
    Return Value an integer or nil
    Description reads the stream given as first argument into the buffer given as second argument, up to the length of the buffer or the length given as third argument if it is smaller; if still unread data remain in the input buffer of the stream object, these data are returned first and no actual read occurs on the system file descriptor; the next stream-read-char , stream-read-line or stream-fread will get the rest of the input buffer if still any and the system file will be read only after input buffer exhaustion; use first stream-clear-input to invalidate the input buffer and force an actual read on the file; the function returns the actual length read, which might be smaller than the buffer or the requested length if either it is what remained in the input buffer or it is only what the system file could give at that moment
    Example (fread mystream buffer1)

    stream-fseek

    (fseek arg1 arg2 arg3 )

    Function Type subr
    Arguments a stream object, an integer, an optional keyword
    Return Value t or nil
    Description positions the file pointer of the file corresponding to the stream object given as first argument to the position given as second argument; the optional third argument is a keyword: 'set indicates that the byte position is relative to the beginning of the file, 'cur indicates that the position is relative to the current or last IO, and 'end  indicates that the position is relative to the end of the file; returns t if the positionning is successful
    Example (fseek mystream 1000 'set)

    stream-ftell

    (ftell arg1 )

    Function Type subr
    Arguments none
    Return Value an integer
    Description returns an integer giving the current position of the file pointer for the stream object given as argument, relative to the beginning of the file
    Example (ftell mystream)

    stream-fwrite

    (fwrite arg1 arg2 arg3 )

    Function Type subr
    Arguments a stream object, a binary, an optional integer
    Return Value an integer or nil
    Description write the buffer given as second argument on the stream given as first argument, up to the length of the buffer or the length given as third argument if shorter; returns the length actually written
    Example (fwrite mystream buffer1)

    stream-read-char

    (read-char arg )

    Function Type subr
    Arguments a stream object
    Return Value an integer or nil
    Description reads a UTF-8 character on the input buffer of the stream object given as argument; if the input buffer is empty, a read() is initiated on the file eventually waiting data if from a terminal or a pipe; the UTF-8 sequences are interpreted by a finite state automaton until complete and returned as one Unicode integer; returns EOF if the input buffer is empty and the stream is at end; stream-read-char returns nil in case of stream error; an error or end of file reached while reconstituting a UTF-8 causes the loss of the sequence and a nil result
    Example (read-char mystream)

    stream-read-char-direct

    (read-char-direct arg )

    Function Type subr
    Arguments a stream object
    Return Value an integer
    Description reads an UTF-8 character directly on a stream object bound to a terminal, without to use the input buffer; there is no echo on the terminal; escape sequences like movement keys are perceived as several separated characters which must be interpreted by the application; UTF-8 sequences are interpreted by a finite state automaton until complete and returned as one Unicode integer
    Example (read-char-direct stdin)

    stream-read-string

    (read-string arg )

    Function Type subr
    Arguments a stream object
    Return Value a string
    Description reads a string from the input buffer of the stream object given as argument and returns it; if the input buffer is empty, a read() is initiated on the stream eventually waiting data if from a terminal or a pipe;if the input buffer is empty and the stream is at end, stream-read-string returns nil and sets EOF to true; the function also returns nil in case of stream error; the string read goes from the current position in the input buffer to just after the last character in the buffer; newline characters or CR-LF sequences can be embedded in the string and are not deleted
    Example (read-string mytream)

    stream-showbin

    (showbin arg1 arg2 arg3 )

    Function Type subr
    Arguments a stream (or subclass) object, a binary block, an integer
    Return Value t or nil
    Description prints a formatted view of the C structure containing buffers and flags which is bound as a binary block to the property lfile of the object; this method is not intended to be used directly but it is called by the class-show method; a showbin method must return t to signal a successful print
    Example none

    stream-unread-char

    (unread-char arg )

    Function Type subr
    Arguments a stream object
    Return Value nil
    Description sets the flag char-in-buffer of the stream object to t so that the last character read by stream-read-char again returned by the next call to stream-read-char or stream-read-string or stream-fread
    Example (unread-char mystream)

    stream-write-char

    (write-char arg1 arg2 )

    Function Type subr
    Arguments a stream object, an integer
    Return Value an integer or nil
    Description writes a UTF-8 character on the stream object; if successful  returns the second argument
    Example (write-char mystream 8364)

    stream-write-line

    (write-line arg1 arg2 )

    Function Type subr
    Arguments a stream object, a string
    Return Value a string
    Description writes the string given as second argument on the stream object given as first argument; if successful returns the second argument; a UNIX newline, ie 0xa, is appended to the string
    Example (write-line mystream "this is a text line" )

    stream-write-string

    (write-string arg1 arg2 )

    Function Type subr
    Arguments a stream object, a string
    Return Value a string
    Description writes the string given as second argument on the stream object given as first argument; if successful returns the second argument; no UNIX newline, ie 0xa is appended to the string
    Example (write-string mystream "this is a text string" )

    Updated 29/11/2008 Copyright © 2008 Walther Waeles
    SourceForge.net Logo