"

 COPYRIGHT (c) 1988 by Claus Gittinger

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

ReadWriteStream subclass:#ExternalStream

       instanceVariableNames:'filePointer mode buffered binary useCRLF hitEOF'

       classVariableNames:'Lobby LastErrorNumber'

       poolDictionaries:''

       category:'Streams-External'

!

ExternalStream comment:'

COPYRIGHT (c) 1988 by Claus Gittinger

              All Rights Reserved

'!

%{

#include <stdio.h>

#include <fcntl.h>

#include <errno.h>

#ifdef hpux

# define fileno(f)      ((f->__fileH << 8) | (f->__fileL))

#endif

%}

!ExternalStream class methodsFor:'documentation'!

documentation

"

    ExternalStream defines protocol common to Streams which have a file-descriptor and 

    represent some file or communicationChannel of the underlying OperatingSystem.

    ExternalStream is abstract; concrete classes are FileStream, PipeStream etc.

    ExternalStreams can be in two modes: text (the default) and binary.

    In text-mode, the elements read/written are characters; 

    while in binary-mode the basic elements are bytes which read/write as SmallIntegers 

    in the range 0..255.

    Also, the stream can be either in buffered or unbuffered mode. In buffered mode,

    data is not written until either a cr is written (in text mode) or a synchronizeOutput

    is sent (in both modes).

    The underlying OperatingSystem streams may either be closed explicitely (sending a close)

    or just forgotten - in this case, the garbage collector will eventually collect the

    object AND a close will be performed automatically (but you will NOT know when this 

    happens - so it is recommended, that you close your files when no longer needed).

    Closing is also suggested since if smalltalk is finished (be it by purpose, or due to

    some crash) the data will not be in the file, if unclosed. 

    All streams understand the close message, so it never hurts to use it (it is defined as 

    a noop in one of the superclasses).

    Most of the methods found here redefine inherited methods for better performance,

    since I/O from/to files should be fast.

    Recovering a snapshot:

    not all streams can be restored to the state they had before - see the implementation of

    reOpen in subclasses for more information.

    For streams sitting on some communication channel (i.e. Pipes and Sockets) you should

    reestablish the stream upon image restart (make someone dependent on ObjectMemory).

    Instance variables:

	filePointer 	<Integer>	the unix FILE*; somehow mapped to an integer

					(notice: not the fd)

        mode 		<Symbol>	#readwrite, #readonly or #writeonly

	buffered 	<Boolean>	true, if buffered (i.e. collects characters - does

					not output immediately)

	binary 		<Boolean>	true if in binary mode (reads bytes instead of chars)

	useCRLF 	<Boolean>	true, if lines should be terminated with crlf instead

					of lf. (i.e. if file is an MSDOS-type file)

	hitEOF 		<Boolean>	true, if EOF was reached

    Class variables:

	Lobby		<Registry>	keeps track of used ext-streams (to free up FILE*'s)

	LastErrorNumber <Integer>	the value of errno (only valid right after the error -

					updated with next i/o operation)

    Question: should lastErrorNumber be kept instance-specific ?

"

! !

!ExternalStream class methodsFor:'initialization'!

initialize

    Lobby isNil ifTrue:[

        Lobby := Registry new.

        "want to get informed when returning from snapshot"

        ObjectMemory addDependent:self

    ]

!

reOpenFiles

    "reopen all files (if possible) after a snapShot load"

    Lobby contentsDo:[:aFileStream |

        aFileStream reOpen

    ]

!

update:something

    "have to reopen files when returning from snapshot"

    something == #returnFromSnapshot ifTrue:[

        self reOpenFiles

    ]

! !

!ExternalStream class methodsFor:'instance creation'!

new

    |newStream|

    newStream := self basicNew.

    newStream text; buffered:true; useCRLF:false; clearEOF.

    ^ newStream

! !

!ExternalStream methodsFor:'instance release'!

disposed

    "some Stream has been collected - close the file if not already done"

    self closeFile

!

closeFile

    "low level close - may be redefined in subclasses"

%{  /* NOCONTEXT */

    if (_INST(filePointer) != nil) {

        int savInt;

        extern int _immediateInterrupt;

        savInt = _immediateInterrupt;

        _immediateInterrupt = 1;

        fclose(MKFD(_INST(filePointer)));

        _immediateInterrupt = savInt;

    }

%}

! !

!ExternalStream methodsFor:'private'!

clearEOF

    hitEOF := false

!

reOpen

    "sent after snapin to reopen streams.

     cannot reopen here since I am abstract and have no device knowledge"

    self class name errorPrint. ': cannot reOpen stream - stream closed' errorPrintNewline.

    filePointer := nil.

    Lobby unregister:self.

! !

!ExternalStream methodsFor:'error handling'!

lastErrorNumber

    "return the last error"

    ^ LastErrorNumber

!

errorNotOpen

    "report an error, that the stream has not been opened"

    ^ self error:(self class name , ' not open')

!

errorReadOnly

    "report an error, that the stream is a readOnly stream"

    ^ self error:(self class name , ' is readonly')

!

errorWriteOnly

    "report an error, that the stream is a writeOnly stream"

    ^ self error:(self class name , ' is writeonly')

!

errorNotBinary

    "report an error, that the stream is not in binary mode"

    ^ self error:(self class name , ' is not in binary mode')

!

errorBinary

    "report an error, that the stream is in binary mode"

    ^ self error:(self class name , ' is in binary mode')

!

errorNotBuffered

    "report an error, that the stream is not in buffered mode"

    ^ self error:(self class name , ' is unbuffered - operation not allowed')

!

argumentMustBeInteger

    "report an error, that the argument must be an integer"

    ^ self error:'argument must be an integer'

!

argumentMustBeCharacter

    "report an error, that the argument must be a character"

    ^ self error:'argument must be a character'

!

argumentMustBeString

    "report an error, that the argument must be a string"

    ^ self error:'argument must be a string'

! !

!ExternalStream methodsFor:'accessing'!

readonly

    "set access mode to readonly"

    mode := #readonly

!

writeonly

    "set access mode to writeonly"

    mode := #writeonly

!

readwrite

    "set access mode to readwrite"

    mode := #readwrite

!

filePointer

    "return the filePointer of the receiver -

     notice: for portability stdio is used; this means you will get

     a FILE * - not a fileDescriptor. 

     (what you really get is a corresponding integer)"

    ^ filePointer

!

fileDescriptor

    "return the fileDescriptor of the receiver -

     notice: this one returns the underlying OSs fileDescriptor -

     this may not be available on all platforms (i.e. non unix systems)."

%{  /* NOCONTEXT */

    FILE *f;

    if (_INST(filePointer) != nil) {

        f = MKFD(_INST(filePointer));

        RETURN ( MKOBJ(fileno(f)) );

    }

%}

.

    ^ self errorNotOpen

!

buffered:aBoolean

    "turn buffering on or off - default is on"

    buffered := aBoolean

!

useCRLF:aBoolean

    "turn on or off CRLF sending (instead of LF only) - default is off"

    useCRLF := aBoolean

!

binary

    "switch to binary mode - default is text"

    binary := true

!

text

    "switch to text mode - default is text"

    binary := false

!

contentsSpecies

    "return the kind of object to be returned by sub-collection builders

     (such as upTo)"

    binary ifTrue:[

        ^ ByteArray

    ].

    ^ String

!

contents

    "return the contents of the file from the current position up-to

     the end. If the stream is in binary mode, a ByteArray containing

     the byte values is returned.

     In text-mode, a collection of strings, each representing one line,

     is returned."

    |text l chunks sizes chunk byteCount cnt bytes offset|

    binary ifTrue:[

        "adding to a ByteArray produces quadratic time-space

         behavior - therefore we allocate chunks, and concatenate them

         at the end."

        chunks := OrderedCollection new.

        sizes := OrderedCollection new.

        byteCount := 0.

        [self atEnd] whileFalse:[

            chunk := ByteArray uninitializedNew:4096.

            cnt := self nextBytes:(chunk size) into:chunk.

            cnt notNil ifTrue:[

                chunks add:chunk.

                sizes add:cnt.

                byteCount := byteCount + cnt

            ]

        ].

        "now, create one big ByteArray"

        bytes := ByteArray uninitializedNew:byteCount.

        offset := 1.

        1 to:chunks size do:[:index |

            chunk := chunks at:index.

            cnt := sizes at:index. 

            bytes replaceFrom:offset to:(offset + cnt - 1) with:chunk.

            offset := offset + cnt

        ].

        ^ bytes

    ].

    text := Text new.

    [self atEnd] whileFalse:[

        l := self nextLine.

        l notNil ifTrue:[

            text add:l

        ]

    ].

    ^ text

! !

!ExternalStream methodsFor:'misc functions'!

open

    "open the stream

     - this must be redefined in subclass"

    ^ self subclassResponsibility

!

close

    "close the stream - tell operating system"

    filePointer isNil ifTrue:[^ self].

    Lobby unregister:self.

    self closeFile.

    filePointer := nil

!

create

    "create the stream

     - this must be redefined in subclass"

    ^ self subclassResponsibility

!

position

    "return the position

     - this must be redefined in subclass"

    ^ self subclassResponsibility

!

position:anInteger

    "set the position

     - this must be redefined in subclass"

    ^ self subclassResponsibility

!

backStep

    "step back one element -

     redefined, since position is redefined here"

    self position:(self position - 1)

!

blocking:aBoolean

    "set/clear the blocking attribute - if set (which is the default)

     a read (using next) on the receiver will block until data is available.

     If cleared, a read operation will immediately return with a value of

     nil."

    filePointer isNil ifTrue:[^ self errorNotOpen].

    ^ OperatingSystem setBlocking:aBoolean on:(self fileDescriptor)

!

async:aBoolean

    "set/clear the async attribute - if set the availability of data on 

     the receiver will trigger an ioInterrupt.

     If cleared (which is the default) no special notification is made."

    filePointer isNil ifTrue:[^ self errorNotOpen].

    aBoolean ifTrue:[

        ^ OperatingSystem enableIOInterruptsOn:(self fileDescriptor)

    ].

    ^ OperatingSystem disableIOInterruptsOn:(self fileDescriptor)

!

ioctl:ioctlNumber

    "to provide a simple ioctl facility - an ioctl is performed

     on the underlying file; no arguments are passed."

%{  /* NOCONTEXT */

    FILE *f;

    int ret, ioNum, ioArg;

    int savInt;

    extern int _immediateInterrupt;

    extern errno;

    if (_INST(filePointer) != nil) {

        if (_isSmallInteger(ioctlNumber)) {

            ioNum = _intVal(ioctlNumber);

            f = MKFD(_INST(filePointer));

            savInt = _immediateInterrupt;

            _immediateInterrupt = 1;

            do {

                ret = ioctl(fileno(f), ioNum);

            } while ((ret < 0) && (errno == EINTR));

            _immediateInterrupt = savInt;

            if (ret >= 0) {

                RETURN ( _MKSMALLINT(ret) );

            }

            ExternalStream_LastErrorNumber = _MKSMALLINT(errno);

            RETURN ( nil );

        }

    }

%}

.

    filePointer isNil ifTrue:[^ self errorNotOpen].

    self primitiveFailed

!

ioctl:ioctlNumber with:arg

    "to provide a simple ioctl facility - an ioctl is performed

     on the underlying file; the argument is passed as argument.

     If the argument is a number, its directly passed; if its a

     kind of ByteArray (ByteArray, String or Structure) a pointer to

     the data is passed. This allows performing most ioctls - however,

     it might be tricky to setup the buffer."

    |isStructure|

    isStructure := arg isKindOf:ByteArray.

%{

    FILE *f;

    int ret, ioNum, savInt;

    extern int _immediateInterrupt;

    extern errno;

    if (_INST(filePointer) != nil) {

        if (_isSmallInteger(ioctlNumber)