Class: PipeStream

• Inheritance
• Description
• Related information
• Class protocol
  • Signal constants
  • initialization
  • instance creation
• Instance protocol
  • accessing
  • closing
  • finalization
  • private

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--ReadWriteStream
                  |
                  +--ExternalStream
                     |
                     +--NonPositionableExternalStream
                        |
                        +--PipeStream

Package:

stx:libbasic

Category:

Streams-External

Version:

rev: 1.111 date: 2010/02/09 18:01:01

user: stefan

file: PipeStream.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

Pipestreams allow reading or writing from/to a unix command.
For example, to get a stream reading the output of an 'ls -l'
command, a PipeStream can be created with:

    PipeStream readingFrom:'ls -l'

the characters of the commands output can be read using the
standard stream messages as next, nextLine etc.

Example for writing to a command:

    PipeStream writingTo:'cat >/tmp/x'

Bidirectional pipestreams (supporting both reading an writing) may be used for filters:

    PipeStream bidirectionalFor:'sed -e ''s/Hello/Greetings/'''

Buffered pipes do not work with Linux - the stdio library seems to be
buggy (trying to restart the read ...)

Related information:

    ExternalStream
    FileStream
    Socket
    OperatingSystem

Class protocol:

 brokenPipeSignal

return the signal used to handle SIGPIPE unix-signals.
Since SIGPIPE is asynchronous, we can't decide which smalltalk process
should handle BrokenPipeSignal. So the system doesn't raise
BrokenPipeSignal for SIGPIPE any longer.

 initialize

setup the signal

 bidirectionalFor: commandString

create and return a new bidirectonal pipeStream which can both be written to
and read from the unix command given by commandString.
The commands error output is send to my own error output.

 bidirectionalFor: commandString errorDisposition: errorDisposition inDirectory: aDirectory

create and return a new bidirectonal pipeStream which can both be written to
and read from the unix command given by commandString.
The directory will be changed to aDirectory while
executing the command. Use this if a command is to be
executed in another directory, to avoid any OS dependencies
in your code.

errorDisposition may be one of #discard, #inline or #stderr (default).
#discard causes stderr to be discarded (/dev/null),
#inline causes it to be written to smalltalks own stdout and
#stderr causes it to be written to smalltalks own stderr.
Nil is treated like #stderr

 readingFrom: commandString

create and return a new pipeStream which can read from the unix command
given by commandString.
The commands error output is send to my own error output.

 readingFrom: commandString errorDisposition: errorDisposition inDirectory: aDirectory

similar to #readingFrom, but changes the directory while
executing the command. Use this if a command is to be
executed in another directory, to avoid any OS dependencies
in your code.
errorDisposition may be one of #discard, #inline or #stderr (default).
#discard causes stderr to be discarded (/dev/null),
#inline causes it to be merged into the PipeStream and
#stderr causes it to be written to smalltalks own stderr.
Nil is treated like #stderr

 readingFrom: commandString inDirectory: aDirectory

similar to #readingFrom, but changes the directory while
executing the command. Use this if a command is to be
executed in another directory, to avoid any OS dependencies
in your code.
The commands error output is send to my own error output.

 writingTo: commandString

create and return a new pipeStream which can write to the unix command
given by command.

 writingTo: commandString errorDisposition: errorDisposition inDirectory: aDirectory

similar to #writingTo, but changes the directory while
executing the command. Use this if a command is to be
executed in another directory, to avoid any OS dependencies
in your code.
errorDisposition may be one of #discard, #inline or #stderr (default).
#discard causes stderr to be discarded (/dev/null),
#inline causes it to be written to smalltalks own stdout and
#stderr causes it to be written to smalltalks own stderr.
Nil is treated like #stderr

 writingTo: commandString inDirectory: aDirectory

create and return a new pipeStream which can write to the unix command
given by commandString. The command is executed in the given directory.

Instance protocol:

 commandString

return the command string

 exitStatus

return the exitStatus

 pid

return pid

 shutDown

close the Stream and terminate the command

 shutDownOutput

signal to the pipestream's command, that no more data will be sent

 finalize

redefined to avoid blocking in close.

 protected closeFile

low level close
This waits for the command to finish.
Use shutDown for a fast (nonBlocking) close.

 closeFileDescriptor

alternative very low level close
This closes the underlying OS-fileDescriptor
- and will NOT write any buffered data to the stream.
You have been warned.

 exitAction: aBlock

define a block to be evaluated when the pipe is closed.
This is only used with VMS, to remove any temporary COM file.
(see readingFrom:inDirectory:)

 openPipeFor: aCommandString withMode: rwMode errorDisposition: errorDisposition inDirectory: aDirectory

open a pipe to the OS command in commandString;
rwMode may be 'r' or 'w' or 'r+'.
errorDisposition controls where the stdErr output should go,
and may be one of #discard, #inline or #stderr (default).
#discard causes stderr to be discarded (/dev/null),
#inline causes it to be written to smalltalks own stdout and
#stderr causes it to be written to smalltalks own stderr.
Nil is treated like #stderr

 terminatePipeCommand

 waitForPipeCommandWithTimeout: seconds

wait for the pipe command to terminate itself.
Return true, if a timeout occurred.