eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'PipeStream':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: PipeStream

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--ReadWriteStream
                  |
                  +--ExternalStream
                     |
                     +--NonPositionableExternalStream
                        |
                        +--PipeStream
                           |
                           +--UnixPTYStream
Package:
stx:libbasic
Category:
Streams-External
Version:
rev: 1.161 date: 2023/09/26 14:00:59
user: stefan
file: PipeStream.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


Pipestreams allow reading or writing from/to a unix or dos 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 command's output can be read using the
standard stream messages, such 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 -u -e ''s/Hello/Greetings/'''

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


copyright
COPYRIGHT (c) 1989 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.

Class protocol:

Signal constants
o  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.

class initialization
o  initialize
setup the signal

instance creation
o  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.

Usage example(s): 

     |p|

     p := PipeStream bidirectionalFor:'cat -u'.
     p nextPutAll:'Wer ist der Bürgermeister von Wesel'; cr.
     Transcript showCR:p nextLine.
     p close

Usage example(s): 

        |p|

        p := PipeStream bidirectionalFor:'sed -u -e ''s/Hello/Greetings/'''.
        p nextPutAll:'Hello world'; cr.
        p shutDownOutput.
        Transcript showCR:p nextLine.
        p close

Usage example(s): 

        |p|

        p := PipeStream bidirectionalFor:'wc'.
        p nextPutAll:'Hello world'; cr.
        p shutDownOutput.
        Transcript showCR:p nextLine.
        p close

o  bidirectionalFor: commandString errorDisposition: errorDispositionSymbolOrStream environment: aShellEnvironmentOrNil 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 a stream or one of #discard, #inline or #stderr (default).
#discard causes stderr to be discarded (/dev/null),
#inline causes it to be written to smalltalk's own stdout
#stderr causes it to be written to smalltalk's own stderr.
a stream causes stderr to be sent to that stream (internal or external)
Nil is treated like #stderr

o  bidirectionalFor: commandString errorDisposition: errorDispositionSymbolOrStream 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 a stream or one of #discard, #inline or #stderr (default).
#discard causes stderr to be discarded (/dev/null),
#inline causes it to be written to smalltalk's own stdout
#stderr causes it to be written to smalltalk's own stderr.
a stream causes stderr to be sent to that stream (internal or external)
Nil is treated like #stderr

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

Usage example(s): 

    |p|

    p := PipeStream readingFrom:'ls -l'.
    Transcript showCR:p nextLine.
    p close

Usage example(s): 

    |p|

    p := PipeStream readingFrom:'echo error >&2'.
    Transcript showCR:p nextLine.
    p close

Usage example(s): 

    |s|
    s := PipeStream readingFrom:'sh -c sleep\ 600'.
    (Delay forSeconds:2) wait.
    s abortAndClose

Usage example(s): 

     |p|
     p := PipeStream readingFrom:'dir'.
     Transcript showCR:p nextLine.
     p close

Usage example(s): 

     |p|
     p := PipeStream readingFrom:'dir'.
     Transcript showCR:p nextLine.
     p close

o  readingFrom: commandString environment: aShellEnvironmentOrNil
create and return a new pipeStream which can read from the unix command
given by commandString.
Additional (or changed) environment variables may be defined in
the optioanl dictionary arg aShellEnvironmentOrNil.
The command's error output is send to my own error output.

Usage example(s): 

        |p|

        p := PipeStream readingFrom:'ls -l'.
        Transcript showCR:p nextLine.
        p close

Usage example(s): 

        |p|

        p := PipeStream readingFrom:'echo error >&2'.
        Transcript showCR:p nextLine.
        p close

Usage example(s): 

        |s|
        s := PipeStream readingFrom:'sh -c sleep\ 600'.
        (Delay forSeconds:2) wait.
        s abortAndClose

Usage example(s): 

        |p|
        p := PipeStream readingFrom:'dir'.
        Transcript showCR:p nextLine.
        p close

Usage example(s): 

        |p|
        p := PipeStream readingFrom:'dir'.
        Transcript showCR:p nextLine.
        p close

o  readingFrom: commandString environment: aShellEnvironmentOrNil 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.
Additional (or changed) environment variables may be defined in
the optioanl dictionary arg aShellEnvironmentOrNil.
The command's error output is send to my own error output.

o  readingFrom: commandString errorDisposition: errorDispositionSymbolOrStream
create and return a new pipeStream which can read from the unix command
given by commandString.
errorDisposition may be a stream or 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 smalltalk's own stderr.
a stream causes stderr to be sent to that stream (internal or external)
Nil is treated like #stderr

Usage example(s): 

        |p|

        p := PipeStream readingFrom:'ls -l'.
        Transcript showCR:p nextLine.
        p close

Usage example(s): 

        |p|

        p := PipeStream readingFrom:'echo error >&2'.
        Transcript showCR:p nextLine.
        p close

Usage example(s): 

        |s|
        s := PipeStream readingFrom:'sh -c sleep\ 600'.
        (Delay forSeconds:2) wait.
        s abortAndClose

Usage example(s): 

        |p|
        p := PipeStream readingFrom:'dir'.
        Transcript showCR:p nextLine.
        p close

Usage example(s): 

        |p|
        p := PipeStream readingFrom:'dir'.
        Transcript showCR:p nextLine.
        p close

o  readingFrom: commandString errorDisposition: errorDispositionSymbolOrStream environment: aShellEnvironmentOrNil 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.
Additional (or changed) environment variables may be defined in
the optioanl dictionary arg aShellEnvironmentOrNil.
errorDisposition may be a stream or 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 smalltalk's own stderr.
a stream causes stderr to be sent to that stream (internal or external)
Nil is treated like #stderr

Usage example(s): 

        |p|

        p := PipeStream readingFrom:'bla' errorDisposition:Transcript inDirectory:nil.
        Transcript showCR:p nextLine.
        p close

Usage example(s): 

        |p|

        p := PipeStream readingFrom:'bla' errorDisposition:#inline inDirectory:nil.
        Transcript showCR:p nextLine.
        p close

o  readingFrom: commandString errorDisposition: errorDispositionSymbolOrStream 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 a stream or 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 smalltalk's own stderr.
a stream causes stderr to be sent to that stream (internal or external)
Nil is treated like #stderr

Usage example(s): 

        |p|

        p := PipeStream readingFrom:'bla' errorDisposition:Transcript inDirectory:nil.
        Transcript showCR:p nextLine.
        p close

Usage example(s): 

        |p|

        p := PipeStream readingFrom:'bla' errorDisposition:#inline inDirectory:nil.
        Transcript showCR:p nextLine.
        p close

o  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 command's error output is send to my own error output.

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

o  writingTo: commandString environment: aShellEnvironmentOrNil
create and return a new pipeStream which can write to the unix command
given by command.
Additional (or changed) environment variables may be defined in
the optioanl dictionary arg aShellEnvironmentOrNil.

o  writingTo: commandString environment: aShellEnvironmentOrNil inDirectory: aDirectory
create and return a new pipeStream which can write to the unix command
given by commandString.
Additional (or changed) environment variables may be defined in
the optioanl dictionary arg aShellEnvironmentOrNil.
The command is executed in the given directory.

o  writingTo: commandString errorDisposition: errorDispositionSymbolOrStream environment: aShellEnvironmentOrNil 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.
Additional (or changed) environment variables may be defined in
the optioanl dictionary arg aShellEnvironmentOrNil.
errorDisposition may be a stream or one of #discard, #inline or #stderr (default).
#discard causes stderr to be discarded (/dev/null),
#inline causes it to be written to smalltalk's own stdout
#stderr causes it to be written to smalltalk's own stderr.
Nil is treated like #stderr

o  writingTo: commandString errorDisposition: errorDispositionSymbolOrStream 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 a stream or one of #discard, #inline or #stderr (default).
#discard causes stderr to be discarded (/dev/null),
#inline causes it to be written to smalltalk's own stdout
#stderr causes it to be written to smalltalk's own stderr.
Nil is treated like #stderr

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

utilities
o  outputFromCommand: aCommand
open a pipe reading from aCommand and return the complete output as a string.
If the command cannot be executed, return nil.
The command's current directory will be the smalltalk current directory.
Only stdout is returned;
the command's error output is send to my own error output.

Usage example(s): 

     PipeStream outputFromCommand:'ls -l'

o  outputFromCommand: aCommand environment: environmentOrNil inDirectory: aDirectoryOrNil
open a pipe reading from aCommand and return the complete output as a string.
If the command cannot be executed, return nil.
The current directory of the command will be aDirectoryOrNil
or the smalltalk's current directory (if nil).
Any stderr output will be discarded (not included) in the returned cmdOutput.

Usage example(s): 

     PipeStream outputFromCommand:'ls -l' inDirectory:nil
     PipeStream outputFromCommand:'ls -l' inDirectory:'/'
     PipeStream outputFromCommand:'ls -l' inDirectory:'/etc'
     PipeStream outputFromCommand:'echo hello >&2' inDirectory:'/etc'

o  outputFromCommand: aCommand errorDisposition: errorDispositionSymbolOrStream
open a pipe reading from aCommand and return the complete output as a string.
If the command cannot be executed, return nil.
The command will be executed in smalltalk's current directory.
errorDisposition may be a stream or 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 smalltalk's own stderr.
a stream causes stderr to be sent to that stream (internal or external)
Nil is treated like #stderr

o  outputFromCommand: aCommand errorDisposition: errorDispositionSymbolOrStream environment: environmentOrNil inDirectory: aDirectoryOrNil
open a pipe reading from aCommand and return the complete output as a string.
If the command cannot be executed, return nil.
The current directory of the command will be aDirectoryOrNil
or the smalltalk's current directory (if nil).
errorDisposition may be a stream or 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 smalltalk's own stderr.
a stream causes stderr to be sent to that stream (internal or external)
Nil is treated like #stderr

Usage example(s): 

     PipeStream outputFromCommand:'ls -l' inDirectory:nil
     PipeStream outputFromCommand:'ls -l' inDirectory:'/'
     PipeStream outputFromCommand:'ls -l' inDirectory:'/etc'

o  outputFromCommand: aCommand errorDisposition: errorDispositionSymbolOrStream inDirectory: aDirectoryOrNil
open a pipe reading from aCommand and return the complete output as a string.
If the command cannot be executed, return nil.
The current directory of the command will be aDirectoryOrNil
or the smalltalk's current directory (if nil).
errorDisposition may be a stream or 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 smalltalk's own stderr.
a stream causes stderr to be sent to that stream (internal or external)
Nil is treated like #stderr

Usage example(s): 

     PipeStream outputFromCommand:'ls -l' inDirectory:nil
     PipeStream outputFromCommand:'ls -l' inDirectory:'/'
     PipeStream outputFromCommand:'ls -l' inDirectory:'/etc'

o  outputFromCommand: aCommand inDirectory: aDirectoryOrNil
open a pipe reading from aCommand and return the complete output as a string.
If the command cannot be executed, return nil.
The current directory of the command will be aDirectoryOrNil
or the smalltalk's current directory (if nil).
Any stderr output will be discarded (not included) in the returned cmdOutput.

Usage example(s): 

     PipeStream outputFromCommand:'ls -l' inDirectory:nil
     PipeStream outputFromCommand:'ls -l' inDirectory:'/'
     PipeStream outputFromCommand:'ls -l' inDirectory:'/etc'
     PipeStream outputFromCommand:'echo hello >&2' inDirectory:'/etc'

Instance protocol:

accessing
o  commandString
return the command string

o  exitStatus
return the exitStatus

o  osProcess
return the underlying osProcess

o  pid
return the osProcess' pid

o  setCommandString: aString
for OSProcess only (so we see the command in the stream monitor)

closing
o  abortAndClose
close the Stream and terminate the command

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

o  shutDown
this is a historic leftover kept for backward compatibility.
The name collides with the same name in Socket, which does
not hard terminate the connection.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

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

finalization
o  finalize
redefined to avoid blocking in close.

private
o  openPipeFor: aCommandString withMode: rwMode errorDisposition: errorDisposition environment: aShellEnvironmentOrNil 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.

o  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

o  terminatePipeCommand

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

testing
o  finishedWithSuccess
return true if so

o  isPipeStream

Examples:


reading: 
  |p output|

  p := PipeStream readingFrom:'ls -l'.
  output := p upToEnd.
  p close.
  Transcript showCR:output
bidirectional: (must add a '-u' argument, because otherwise sed will read a big junk waiting for more input, before generating any output) Notice: OSX sed does not support a '-u' option (sigh) 
  |p|

  p := PipeStream bidirectionalFor:'sed -u -e s/Hello/Greetings/'.
  p nextPutLine:'bla'.
  Transcript showCR:p nextLine.
  p nextPutLine:'foo Hello'.
  Transcript showCR:p nextLine.
  p nextPutLine:'bar'.
  Transcript showCR:p nextLine.
  p close.
error output is on my stderr: 
  |p|

  p := PipeStream readingFrom:'echo hello1; echo error>&2; echo hello2'.
  Transcript showCR:p upToEnd.
  p close.
error output is included: 
  |p|

  p := PipeStream readingFrom:'echo hello1; echo error>&2; echo hello2' errorDisposition:#stdout.
  Transcript showCR:p upToEnd.
  p close.
error output is separate: 
  |p errStream|

  errStream := '' writeStream.
  p := PipeStream readingFrom:'echo hello1; echo error>&2; echo hello2' errorDisposition:errStream.
  Transcript showCR:'output:'; showCR:p upToEnd; cr.
  p close.
  Transcript showCR:'error:'; showCR:errStream contents; cr.

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Tue, 03 Dec 2024 17:21:21 GMT