A channel that uses a operating system pipe between the current process and a sub-process.
![]() | Construction |
![]() | Overrides from class PObject |
![]() | Overrides from class PChannel |
![]() | New member functions |
![]() | subProgName The fully qualified path name for the sub-program executable. |
Information functions
Reading functions
Writing functions
Miscellaneous functions
Error functions
Run Time Type functions
Comparison functions
I/O functions
A channel that uses a operating system pipe between the current process and a sub-process. On platforms that supportmulti-processing , the sub-program is executed concurrently with the calling process.Where full multi-processing is not supported then the sub-program is run with its input supplied from, or output captured to, a disk file. The current process is then suspended during the execution of the sub-program. In the latter case the semantics of the Execute() and Close() functions change from the usual for channels.
Note that for platforms that do not support multi-processing, the current process is suspended until the sub-program terminates. The input and output of the sub-program is transferred via a temporary file. The exact moment of execution of the sub-program depends on the mode. If mode is ReadOnly then it is executed immediately and its output captured. In WriteOnly mode the sub-program is run when the Close() function is called, or when the pipe channel is destroyed. In ReadWrite mode the sub-program is run when the Execute() function is called indicating that the output from the current process to the sub-program has completed and input is now desired.
The CanReadAndWrite() function effectively determines whether full multi-processing is supported by the platform. Note that this is different to whether
multi-threading is supported.
WriteOnly
ReadWrite
ReadWriteStd
See the Open() function for details of various parameters.
See the Open() function for details of various parameters.
See the Open() function for details of various parameters.
See the Open() function for details of various parameters.
PPipeChannel( const PString & subProgram, OpenMode mode = ReadWrite, BOOL searchPath = TRUE, BOOL stderrSeparate = FALSE )
mode - Mode for the pipe channel.
searchPath - Flag for system PATH to be searched.
stderrSeparate - Standard error is on separate pipe PPipeChannel( const PString & subProgram, const PStringArray & argumentList, OpenMode mode = ReadWrite, BOOL searchPath = TRUE, BOOL stderrSeparate = FALSE )
argumentList - Array of arguments to sub-program.
mode - Mode for the pipe channel.
searchPath - Flag for system PATH to be searched.
stderrSeparate - Standard error is on separate pipe PPipeChannel( const PString & subProgram, const PStringToString & environment, OpenMode mode = ReadWrite, BOOL searchPath = TRUE, BOOL stderrSeparate = FALSE )
environment - Array of arguments to sub-program.
mode - Mode for the pipe channel.
searchPath - Flag for system PATH to be searched.
stderrSeparate - Standard error is on separate pipe PPipeChannel( const PString & subProgram, const PStringArray & argumentList, const PStringToString & environment, OpenMode mode = ReadWrite, BOOL searchPath = TRUE, BOOL stderrSeparate = FALSE )
argumentList - Array of arguments to sub-program.
environment - Array of arguments to sub-program.
mode - Mode for the pipe channel.
searchPath - Flag for system PATH to be searched.
stderrSeparate - Standard error is on separate pipe ~PPipeChannel()
If there are no more characters available as the sub-program has
stopped then the number of characters available is returned. This is
similar to end of file for the PFile channel. The GetErrorCode() function should be consulted after Read() returns
FALSE to determine what caused the failure.
If the sub-program has completed its run then this function will fail
returning FALSE. The GetErrorCode() function should be consulted after Write() returns
FALSE to determine what caused the failure.
For WriteOnly or ReadWrite mode pipe channels
on platforms that do no support concurrent multi-processing and have
not yet called the Execute() function this will run the
sub-program.
virtual BOOL Read( void * buf, PINDEX len )
len - Maximum number of bytes to read into the buffer.virtual BOOL Write( const void * buf, PINDEX len )
len - Number of bytes to write.virtual BOOL Close()
If the mode is ReadOnly then the stdout of the
sub-program is supplied via the Read() calls of the PPipeChannel.
The sub-programs input is set to the platforms null device (eg
/dev/nul). If mode is WriteOnly then Write() calls of the
PPipeChannel are suppied to the sub-programs stdin and its
stdout is sent to the null device. If mode is ReadWrite then both read and write actions can
occur. The subProgram parameter may contain just the path of the
program to be run or a program name and space separated arguments,
similar to that provided to the platforms command processing shell.
Which use of this parameter is determiend by whether arguments are
passed via the argumentPointers or
argumentList parameters. The searchPath parameter indicates that the system PATH
for executables should be searched for the sub-program. If FALSE then
only the explicit or implicit path contained in the
subProgram parameter is searched for the executable. The stderrSeparate parameter indicates that the standard
error stream is not included in line with the standard output stream.
In this case, data in this stream must be read using the
ReadStandardError() function. The
of null terminated strings of the form name=value. If NULL is passed
then the same invironment as calling process uses is passed to the
child process.
For platforms that do support concurrent multi-processing this will
close the pipe from the current process to the sub-process. As the sub-program is run immediately and concurrently, this will just
give an end of file to the stdin of the remote process. This is often
necessary.
BOOL Open( const PString & subProgram, const PStringArray & argumentList, OpenMode mode = ReadWrite, BOOL searchPath = TRUE, BOOL stderrSeparate = FALSE )
argumentList - Array of arguments to sub-program.
mode - Mode for the pipe channel.
searchPath - Flag for system PATH to be searched.
stderrSeparate - Standard error is on separate pipeBOOL Open( const PString & subProgram, const PStringToString & environment, OpenMode mode = ReadWrite, BOOL searchPath = TRUE, BOOL stderrSeparate = FALSE )
environment - Array of arguments to sub-program.
mode - Mode for the pipe channel.
searchPath - Flag for system PATH to be searched.
stderrSeparate - Standard error is on separate pipeBOOL Open( const PString & subProgram, const PStringArray & argumentList, const PStringToString & environment, OpenMode mode = ReadWrite, BOOL searchPath = TRUE, BOOL stderrSeparate = FALSE )
argumentList - Array of arguments to sub-program.
environment - Array of arguments to sub-program.
mode - Mode for the pipe channel.
searchPath - Flag for system PATH to be searched.
stderrSeparate - Standard error is on separate pipeconst PFilePath& GetSubProgram() const
BOOL Execute()
BOOL IsRunning() const
int GetReturnCode() const
int WaitForTermination()
int WaitForTermination( const PTimeInterval & timeout )
BOOL Kill( int signal = 9 )
BOOL ReadStandardError( PString & errors, BOOL wait = FALSE )
wait - Flag to indicate if function should blockstatic BOOL CanReadAndWrite()
Alphabetic index HTML hierarchy of classes or Java