"

 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 didWrite lastErrorNumber'

       classVariableNames:'Lobby LastErrorNumber

			   StreamErrorSignal ReadErrorSignal WriteErrorSignal

			   InvalidReadSignal InvalidWriteSignal InvalidModeSignal

			   OpenErrorSignal StreamNotOpenSignal'

       poolDictionaries:''

       category:'Streams-External'

!

ExternalStream comment:'

COPYRIGHT (c) 1988 by Claus Gittinger

	      All Rights Reserved

'!

!ExternalStream primitiveDefinitions!

%{

#include <stdio.h>

#define _STDIO_H_INCLUDED_

#include <fcntl.h>

#define _FCNTL_H_INCLUDED_

#include <errno.h>

#define _ERRNO_H_INCLUDED_

#ifdef hpux

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

#endif

/*

 * stdio library requires an fseek before reading whenever a file

 * is open for read/write and the last operation was a write.

 * (also vice-versa).

 * All code should use the following macro before doing reads:

 */

#define __READING__(f)                          \

    if ((_INST(didWrite) != false)              \

     && (_INST(mode) == @symbol(readwrite))) {  \

	_INST(didWrite) = false;                \

	fseek(f, 0L, 1); /* needed in stdio */  \

    }

#define __WRITING__(f)                          \

    if ((_INST(didWrite) != true)               \

     && (_INST(mode) == @symbol(readwrite))) {  \

	_INST(didWrite) = true;                 \

	fseek(f, 0L, 1); /* needed in stdio */  \

    }

/*

 * on some systems errno is a macro ... check for it here

 */

#ifndef errno

 extern errno;

#endif

%}

! !

!ExternalStream class methodsFor:'documentation'!

copyright

"

 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.

"

!

version

"

"

!

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-mode.

    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).

    FileStreams are reopened and positioned to their offset they had at snapshot time.

    This may fail, if the file was removed or renamed - or lead to confusion

    if the contents changed in the meantime.

    Therefore, it is a good idea to reopen files and check for these things at restart time.

    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

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

					updated with next i/o operation)

    Class variables:

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

	StreamErrorSignal       <Signal> parent of all stream errors

	ReadErrorSignal         <Signal> raised on read errors

	WriteErrorSignal        <Signal> raised on write errors

	InvalidReadSignal       <Signal> raised on read from writeonly stream

	InvalidWriteSignal      <Signal> raised on write to readonly stream 

	InvalidModeSignal       <Signal> raised on text I/O with binary-stream

					 or binary I/O with text-stream

	OpenErrorSignal         <Signal> raised if open fails

	StreamNotOpenSignal     <Signal> raised on I/O with non-open stream

    Additional notes:

      This class is implemented using the underlying stdio-c library package, which

      has both advantages and disadvantages: since it is portable (posix defined), porting

      ST/X to non-Unix machines is simplified. The disadvantage is that the stdio library

      has big problems handling unbounded Streams, since the EOF handling in stdio is

      not prepared for data to arrive after EOF has been reached - time will show, if we need

      a complete rewrite for UnboundedStream ...

      Also, depending on the system, the stdio library behaves infriendly when signals

      occur while reading (for example, timer interrupts) - on real unixes (i.e. BSD) the signal

      is handled transparently - on SYS5.3 (i.e. non unixes :-) the read operation returns

      an error and errno is set to EINTR. Thats what the ugly code around all getc-calls is for.

      Notice that typical stdio's use a single errno global variable to return an error code,

      this was bad design in the stdio lib (right from the very beginning), since its much

      harder to deal with this in the presence of lightweight processes, where errno gets

      overwritten by an I/O operation done in another thread. (stdio should have been written

      to return errno as a negative number ...).

      To deal with this, the scheduler treats errno like a per-thread private variable,

      and saves/restores the errno setting when switching to another thread.

      (Notice that some thread packages do this also, but ST/X's thread implementation

      does not depend on those, but instead uses a portable private package).

      Finally, if an stdio-stream is open for both reading and writing, we have to call

      fseek whenever we are about to read after write and vice versa.

      Two macros (__READING__ and __WRITING__) have been defined to be used before every

      fread/fgetc and fwrite/putc respectively.

"

! !

!ExternalStream class methodsFor:'initialization'!

initialize

    StreamErrorSignal isNil ifTrue:[

	StreamErrorSignal := ErrorSignal newSignalMayProceed:false.

	StreamErrorSignal nameClass:self message:#streamErrorSignal.

	StreamErrorSignal notifierString:'I/O error'.

	OpenErrorSignal := StreamErrorSignal newSignalMayProceed:true.

	OpenErrorSignal nameClass:self message:#openErrorSignal.

	OpenErrorSignal notifierString:'open error'.

	ReadErrorSignal := StreamErrorSignal newSignalMayProceed:false.

	ReadErrorSignal nameClass:self message:#readErrorSignal.

	ReadErrorSignal notifierString:'read error'.

	WriteErrorSignal := StreamErrorSignal newSignalMayProceed:false.

	WriteErrorSignal nameClass:self message:#writeErrorSignal.

	WriteErrorSignal notifierString:'write error'.

	InvalidReadSignal := ReadErrorSignal newSignalMayProceed:false.

	InvalidReadSignal nameClass:self message:#invalidReadSignal.

	InvalidReadSignal notifierString:'write error'.

	InvalidWriteSignal := WriteErrorSignal newSignalMayProceed:false.

	InvalidWriteSignal nameClass:self message:#invalidWriteSignal.

	InvalidWriteSignal notifierString:'write error'.

	InvalidModeSignal :=  StreamErrorSignal newSignalMayProceed:false.

	InvalidModeSignal nameClass:self message:#invalidModeSignal.

	InvalidModeSignal notifierString:'binary/text mode mismatch'.

	StreamNotOpenSignal := StreamErrorSignal newSignalMayProceed:false.

	StreamNotOpenSignal nameClass:self message:#streamNotOpenSignal.

	StreamNotOpenSignal notifierString:'stream is not open'.

    ].

    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 do:[:aFileStream |

	aFileStream reOpen

    ]

!

update:something

    "have to reopen files when returning from snapshot"

    something == #returnFromSnapshot ifTrue:[

	self reOpenFiles

    ]

! !

!ExternalStream class methodsFor:'Signal constants'!

streamErrorSignal

    "return the parent of all stream errors;

     handling this one also handles all other errors.

     Also, this one is raised for errors not related to read/write

     operations, such as failed ioctls"

    ^ StreamErrorSignal

!

readErrorSignal

    "return the signal raised on read errors"

    ^ ReadErrorSignal

!

writeErrorSignal

    "return the signal raised on write errors"

    ^ WriteErrorSignal

!

invalidReadSignal

    "return the signal raised when reading from writeonly streams"

    ^ InvalidReadSignal

!

invalidWriteSignal

    "return the signal raised when writing to readonly streams"

    ^ InvalidWriteSignal

!

invalidModeSignal

    "return the signal raised when doing text-I/O with a binary stream

     or binary-I/O with a text stream"

    ^ InvalidModeSignal

!

streamNotOpenSignal

    "return the signal raised on I/O with closed streams"

    ^ StreamNotOpenSignal

!

openErrorSignal

    "return the signal raised when a file open failed"

    ^ OpenErrorSignal

! !

!ExternalStream class methodsFor:'instance creation'!

new

    |newStream|

    newStream := self basicNew.

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

    ^ newStream

! !

!ExternalStream class methodsFor:'error handling'!

lastErrorNumber

    "return the errno of the last error"

    ^ LastErrorNumber

    "

     ExternalStream lastErrorNumber

    "

!

lastErrorString

    "return a message string describing the last error"

    ^ OperatingSystem errorTextForNumber:LastErrorNumber

    "

     ExternalStream lastErrorString

    "

! !

!ExternalStream methodsFor:'instance release'!

shallowCopyForFinalization

    "return a copy for finalization-registration;

     since all we need at finalization time is the fileDescriptor,

     a cheaper copy is possible."

    ^ self class basicNew setFilePointer:filePointer

!

setFilePointer:anInteger

    filePointer := anInteger

!

disposed

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

    self closeFile

!

shutDown

    "close the stream - added for protocol compatibility with PipeStream.

     see comment there"

    self closeFile

!

closeFile

    "low level close - may be redefined in subclasses"

%{  /* NOCONTEXT */

    OBJ fp;

    if ((fp = _INST(filePointer)) != nil) {

	_INST(filePointer) = nil;

	__BEGIN_INTERRUPTABLE__

	fclose(MKFD(fp));

	__END_INTERRUPTABLE__

    }

%}

! !

!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' errorPrintNL.

    filePointer := nil.

    Lobby unregister:self.

!

setLastError:aNumber

    lastErrorNumber := aNumber

! !

!ExternalStream methodsFor:'error handling'!

lastErrorNumber

    "return the last error"

    ^ lastErrorNumber

!

lastErrorString

    "return a message string describing the last error"

    (lastErrorNumber isNil or:[lastErrorNumber == 0]) ifTrue:[

	^ 'I/O error'

    ].

    ^ OperatingSystem errorTextForNumber:lastErrorNumber

!

errorOpen

    "report an error, that the stream is already opened"

    ^ OpenErrorSignal

	raiseRequestWith:self

	errorString:(self class name , ' is already open')

		 in:thisContext sender

!

openError

    "report an error, that the open failed"

    ^ OpenErrorSignal

	raiseRequestWith:self

	     errorString:('error on open: ' , self lastErrorString)

		      in:thisContext sender

!

errorNotOpen

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

    ^ StreamNotOpenSignal

	raiseRequestWith:self

	     errorString:(self class name , ' not open')

		      in:thisContext sender

!

errorReadOnly

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

    ^ InvalidWriteSignal

	raiseRequestWith:self

	     errorString:(self class name , ' is readonly')

		      in:thisContext sender

!

errorWriteOnly

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

    ^ InvalidReadSignal

	raiseRequestWith:self

	     errorString:(self class name , ' is writeonly')

		      in:thisContext sender

!

errorNotBinary

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

    ^ InvalidModeSignal

	raiseRequestWith:self

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

		      in:thisContext sender

!

errorBinary

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

    ^ InvalidModeSignal

	raiseRequestWith:self

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

		      in:thisContext sender

!

errorNotBuffered

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

    ^ StreamErrorSignal

	raiseRequestWith:self

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

		      in:thisContext sender

!

ioError

    "report an error, that some I/O error occured"