dvi2bitmap dvi2bitmap1.0

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | List of all members
PipeStream Class Reference

Runs an external program, and provides access to the result. More...

`#include <PipeStream.h>`

Inheritance diagram for PipeStream:

## Public Member Functions
| PipeStream (string cmd, string envs="") throw (InputByteStreamError)
| Creates a stream which returns the output of a given command. More...
| ~PipeStream ()
string | getResult (bool allOfFile=false, bool gobbleRest=true) throw (InputByteStreamError)
| Returns the contents of the stream as a string. More...
virtual void | close (void)
| Closes the stream, and reaps the process status. More...
int | getTerminationStatus (void)
| Returns the exit status of the command at the end of the pipe. More...
pid_t | getPid (void) const
| Returns the PID of the running process. More...
Public Member Functions inherited from InputByteStream
| InputByteStream (int fileno) throw (InputByteStreamError)
| Prepares to read a stream from the specified file descriptor, which must be open. More...
| InputByteStream (string srcspec) throw (InputByteStreamError)
| Prepares to read a stream from the specified source. More...
| ~InputByteStream ()
| Closes the file and reclaims any buffers. More...
bool | eof ()
| Indicates whether we are at the end of the file. More...
Byte | getByte (void) throw (InputByteStreamError)
| Reads a byte from the stream. More...
const Byte * | getBlock (unsigned int length) throw (InputByteStreamError)
| Retrieves a block from the current position in the stream. More...
void | skip (unsigned int) throw (InputByteStreamError)
| Skips a given number of bytes forward in the stream. More...
signed int | getSIU (int) throw (InputByteStreamError)
| Obtains an n-byte unsigned integer from the stream, as a signed int. More...
signed int | getSIS (int) throw (InputByteStreamError)
| Obtains an n-byte signed integer from the stream, as a signed int. More...
unsigned int | getUIU (int) throw (InputByteStreamError)
| Obtains an n-byte unsigned integer from the stream, as an unsigned int. More...

## Additional Inherited Members
Static Public Member Functions inherited from InputByteStream
static unsigned int | getUIU (int, const Byte *) throw (InputByteStreamError)
| Obtains an n-byte unsigned integer from the beginning of a `Byte` array, as an unsigned int. More...
static void | setDefaultBufferSize (unsigned int length)
| Sets the default buffer size to be used for reading files. More...
static void | verbosity (const verbosities level)
| Sets the verbosity of this module. More...
static verbosities | getVerbosity (void)
| Returns the verbosity setting of this class. More...
Protected Member Functions inherited from InputByteStream
| InputByteStream ()
| No-argument constructor creates a new InputByteStream object, but does not associate it with any source of bytes. More...
bool | bindToFileDescriptor (int fileno, string filename="", int bufsize=0, bool fillBufferAndClose=false, bool assertIsSeekable=false) throw (InputByteStreamError)
| Binds this stream to a given file descriptor. More...
int | openSourceSpec (string srcspec) throw (InputByteStreamError)
| Opens a source. More...
int | getFD (void) const
| Returns the file descriptor this stream is bound to. More...
void | bufferSeek (unsigned int pos) throw (InputByteStreamError)
| Seeks to a specific point in the buffer. More...
void | reloadBuffer (void)
| Reloads the buffer, presumably after the file descriptor has been adjusted by an extending class. More...

## Detailed Description

Runs an external program, and provides access to the result.

This runs a given command in a forked process, optionally adjusting the environment as it does so. The output from the command is available using the methods of an InputByteStream, plus an additional one which retrieves the entire result as a string.

## Constructor & Destructor Documentation

PipeStream::PipeStream | ( | string | cmd,
|  | string | envs = `""`
| ) |  |
throw | ( | InputByteStreamError
| ) |  |

Creates a stream which returns the output of a given command.

The constructor open a pipe with the given command, and prepares for the results to be read by this class's accessor methods.

If the second argument is omitted, then a default list of environment variables, namely `PATH HOME LOGNAME SHELL TMPDIR`, are inherited from the current environment. If present, it should be a space-separated list of environment variables with optional values: if no equal sign is present, the variable's value is inherited from the current environment. For example, if this list is given as in the form `env1=val1 env2= env3`, then `env1` would receive the value `val1`, `env2` would receive a null value, and `env3` would be inherited.

If the command exits with a non-zero exit status, this is noted on `stderr`, but any output from the command is still returned.

If there's no way of doing this on a particular platform, throw `InputByteStreamError` always.

Parameters

  cmd | the command to be run
  envs | if specified, this is a list of environment variables; if it is an empty string, `""` (the default), then a default list of variables is inherited

Exceptions

  InputByteStreamError | on any errors

References PipeStreamSignalHandling::expectAnother(), normal, NULL, Util::string_list_to_array(), and Util::tokenise_string().

PipeStream::~PipeStream | ( | ) |  |

## Member Function Documentation

void PipeStream::close | ( | void | ) |  |
| virtual

Closes the stream, and reaps the process status.

If the process has not already terminated, this method attempts to kill it, by sending first HUP then KILL. If there is some reason why we can't reap the status – because it has not died or for, say, some permissions reason – we set the returned status to -1. Any data not read from the pipe is discarded.

Reimplemented from InputByteStream.

References InputByteStream::close(), PipeStreamSignalHandling::got_status(), and normal.

pid_t PipeStream::getPid | ( | void | ) |  | const
| inline

Returns the PID of the running process.

After the process has finished, this will return zero.

Returns
  the process's PID, or zero if it has finished

string PipeStream::getResult | ( | bool | allOfFile = `false`,
|  | bool | gobbleRest = `true`
| ) |  |
throw | ( | InputByteStreamError
| ) |  |

Returns the contents of the stream as a string.

If some of the stream has already been read by other methods of this class or its parent, it cannot be re-read. Any trailing whitespace, including end-of-line characters, is stripped.

It's possible that the returned string will be incomplete, if the process failed somehow; irrespective of whether this happened, this returns what it can, and if this condition matters to you, you should check the termination status with `getTerminationStatus`.

Parameters

  allOfFile | if true, then all of the file is read into the string; if false (the default), only the first line is returned, not including the newline or carriage-return which ends the line
  gobbleRest | if true (the default) then gobble the rest of the file; has an effect only if `allOfFile` was false

Returns
  the stream contents (or some of it, depending on the parameter values) as a string

Exceptions

  InputByteStreamError | if there is some problem reading the stream

References normal, SS_STRING, and SSTREAM.

Referenced by PkFont::PkFont().

int PipeStream::getTerminationStatus | ( | void | ) |  |

Returns the exit status of the command at the end of the pipe.

Since this is only available after the process has completed, this invokes close on the stream first. Thus you should not invoke this method until after you have extracted all of the command's output that you want. If `close` is unable to terminate the process for some reason, this returns -1.

If the process exited normally, return the exit status of the command, as opposed to the raw exit status returned from the process, since this is more useful than the raw status with assorted other status information concerning anomalous exits. This status is non-negative. If the process did not exit normally, then return the negative of the raw status information, which we assert will be less than zero.

See waitpid(2) for details.

Returns
  the exit status of the process.

Referenced by PkFont::PkFont().

The documentation for this class was generated from the following files:

- PipeStream.h
- PipeStream.cc