"

 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 InvalidReadSignal InvalidWriteSignal

		InvalidModeSignal OpenErrorSignal StreamNotOpenSignal

		InvalidOperationSignal'

	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

#ifndef SEEK_SET

# define SEEK_SET 0

#endif

#ifndef SEEK_CUR

# define SEEK_CUR 1

#endif

#ifndef SEEK_END

# define SEEK_END 2

#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, SEEK_CUR); /* needed in stdio */  \

    }

#define __WRITING__(f)                          \

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

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

	_INST(didWrite) = true;                 \

	fseek(f, 0L, SEEK_CUR); /* 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)

	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

    OpenErrorSignal isNil ifTrue:[

	OpenErrorSignal := StreamErrorSignal newSignalMayProceed:true.

	OpenErrorSignal nameClass:self message:#openErrorSignal.

	OpenErrorSignal notifierString:'open 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'.

	InvalidOperationSignal :=  StreamErrorSignal newSignalMayProceed:false.

	InvalidOperationSignal nameClass:self message:#invalidOperationSignal.

	InvalidOperationSignal notifierString:'unsupported file operation'.

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

forFileDescriptor:aFileDescriptor mode:mode

    |newStream|

    newStream := self basicNew.

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

    ^ newStream connectTo:aFileDescriptor withMode:mode

    "this will probably fail (15 is a random FD):

     |s|

     s := ExternalStream forFileDescriptor:15 mode:'r'.

     s next.

    "

    "Created: 29.2.1996 / 18:05:00 / cg"

    "Modified: 29.2.1996 / 18:17:07 / cg"

!

forReadWriteToFileDescriptor:aFileDescriptor

    ^ self forFileDescriptor:aFileDescriptor mode:'r+'

    "this will probably fail (15 is a random FD):

     |s|

     s := ExternalStream forReadWriteToFileDescriptor:15.

     s next.

    "

    "Created: 29.2.1996 / 18:15:08 / cg"

    "Modified: 29.2.1996 / 18:16:25 / cg"

!

forReadingFromFileDescriptor:aFileDescriptor

    ^ self forFileDescriptor:aFileDescriptor mode:'r'

    "this will probably fail (15 is a random FD):

     |s|

     s := ExternalStream forReadingFromFileDescriptor:15.

     s next.

    "

    "

     |pipe readFd writeFd rs ws|

     'create OS pipe ...'.

     pipe := OperatingSystem makePipe.

     readFd := pipe at:1.

     writeFd := pipe at:2.

     'connect Smalltalk streams ...'.

     rs := ExternalStream forReadingFromFileDescriptor:readFd.

     ws := ExternalStream forWritingToFileDescriptor:writeFd.

     'read ...'.

     [

     ] forkAt:7.

     'write ...'.

     [

     ] fork.

    "

    "Created: 29.2.1996 / 18:14:24 / cg"

    "Modified: 29.2.1996 / 18:25:02 / cg"

!

forWritingToFileDescriptor:aFileDescriptor

    ^ self forFileDescriptor:aFileDescriptor mode:'w'

    "this will probably fail (15 is a random FD):

     |s|

     s := ExternalStream forWritingToFileDescriptor:15.

     s binary.

     s nextPut:1.

    "

    "Created: 29.2.1996 / 18:14:43 / cg"

    "Modified: 29.2.1996 / 18:15:54 / cg"

!

makePipe

    "return an array with two streams - the first one for reading, the second

     for writing. This is the higher level equivalent of OperatingSystem>>makePipe."

     |pipe rs ws|

     pipe := OperatingSystem makePipe.

     pipe notNil ifTrue:[

     ].

     ^ nil

    "

     |pipe rs ws|

     pipe := ExternalStream makePipe.

     rs := pipe at:1.

     ws := pipe at:2.

     'read ...'.

     [

     ] forkAt:7.

     'write ...'.

     [

     ] fork.

    "

    "Modified: 29.2.1996 / 18:28:36 / cg"

!

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

!

invalidOperationSignal

    "return the signal raised when an unsupported or invalid

     I/O operation is attempted"

    ^ InvalidOperationSignal

!

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

!

streamNotOpenSignal

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

    ^ StreamNotOpenSignal

! !

!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

	    ]