"

 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 LINUX

  /* use inline string macros */

# define __STRINGDEFS__

# include <linuxIntern.h>

#endif

#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))) {  \

    }

#define __WRITING__(f)                          \

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

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

    }

#define __READBYTE__(ret, f, buf, isBuffered)                                 \

    if (isBuffered) {                                                         \

    } else {                                                                  \

   }                                                                          

#define __READBYTES__(ret, f, buf, cnt, isBuffered)                           \

    (ret) = 0;                                                                \

    if (isBuffered) {                                                         \

    } else {                                                                  \

   }

#define __WRITEBYTE__(ret, f, buf, isBuffered)                                \

    if (isBuffered) {                                                         \

    } else {                                                                  \

   }                                                                          

#define __WRITEBYTES__(ret, f, buf, cnt, isBuffered)                          \

    (ret) = 0;                                                                \

    if (isBuffered) {                                                         \

    } else {                                                                  \

   }

/*

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

      Since things get more and more ugly - we will rewrite ExternalStream

      completely, to NOT use any stdio stuff (and do its buffering itself).

      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.

    [author:]

	Claus Gittinger

	Stefan Vogel (many, many fixes ...)

    [see also:]

	FileStream Socket PipeStream

	Filename OperatingSystem

"

! !

!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 with:aParameter from:changedObject

    "have to reopen files when returning from snapshot"

    something == #returnFromSnapshot ifTrue:[

    ]

    "Created: 15.6.1996 / 15:19:59 / cg"

! !

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

     [

	 1 to:10 do:[:i |

	     Transcript showCR:rs nextLine

	 ].

	 rs close.

     ] forkAt:7.

     'write ...'.

     [

	 1 to:10 do:[:i |

	     ws nextPutAll:'hello world '; nextPutAll:i printString; cr

	 ].

	 ws close.

     ] 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."