"

 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

	 classVariableNames:'Lobby LastErrorNumber ReadErrorSignal WriteErrorSignal

	 poolDictionaries:''

	 category:'Streams-External'

!

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

"

!

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 (see Stream class)

	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.

"

!

version

! !

!ExternalStream class methodsFor:'initialization'!

initialize

    OpenErrorSignal isNil ifTrue:[

	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:'read 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:'instance creation'!

new

    |newStream|

    newStream := self basicNew.

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

    ^ newStream

! !

!ExternalStream class methodsFor:'Signal constants'!

invalidModeSignal

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

     or binary-I/O with a text stream"

    ^ InvalidModeSignal

!

invalidReadSignal

    "return the signal raised when reading from writeonly streams"

    ^ InvalidReadSignal

!

invalidWriteSignal

    "return the signal raised when writing to readonly streams"

    ^ InvalidWriteSignal

!

openErrorSignal

    "return the signal raised when a file open failed"

    ^ OpenErrorSignal

!

readErrorSignal

    "return the signal raised on read errors"

    ^ ReadErrorSignal

!

streamNotOpenSignal

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

    ^ StreamNotOpenSignal

!

writeErrorSignal

    "return the signal raised on write errors"

    ^ WriteErrorSignal

! !

!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:'accessing'!

binary

    "switch to binary mode - default is text"

    binary := true

!

buffered:aBoolean

    "turn buffering on or off - default is on"

    buffered := aBoolean

!

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 := StringCollection new.

    [self atEnd] whileFalse:[

	l := self nextLine.

	l isNil ifTrue:[

	    ^ text

	].

	text add:l

    ].

    ^ text

!

contentsOfEntireFile

    "ST-80 compatibility"

    ^ self contents

!

contentsSpecies

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

     (such as upTo)"

    binary ifTrue:[

	^ ByteArray

    ].

    ^ String

!

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;

    OBJ fp;

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

	f = __FILEVal(fp);

	RETURN ( __MKSMALLINT(fileno(f)) );

    }

%}

.

    ^ self errorNotOpen

!

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

     You cannot do much with the returned value 

     - except passing it to a primitive, for example."

    ^ filePointer

!

readonly

    "set access mode to readonly"

    mode := #readonly

!

readwrite

    "set access mode to readwrite"

    mode := #readwrite

!

text

    "switch to text mode - default is text"

    binary := false

!

useCRLF:aBoolean

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

    useCRLF := aBoolean

!

writeonly

    "set access mode to writeonly"

    mode := #writeonly

! !

!ExternalStream methodsFor:'error handling'!

argumentMustBeCharacter

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

    ^ self error:'argument must be a character'

!

argumentMustBeInteger

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

    ^ self error:'argument must be an integer'

!

argumentMustBeString

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

    ^ self error:'argument must be a string'

!

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

!

errorNotBinary

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

    ^ InvalidModeSignal

	raiseRequestWith:self

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