\hypertarget{classPipeStream}{\section{Pipe\-Stream Class Reference}
\label{classPipeStream}\index{Pipe\-Stream@{Pipe\-Stream}}
}


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




{\ttfamily \#include $<$Pipe\-Stream.\-h$>$}

Inheritance diagram for Pipe\-Stream\-:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[height=2.000000cm]{classPipeStream}
\end{center}
\end{figure}
\subsection*{Public Member Functions}
\begin{DoxyCompactItemize}
\item 
\hyperlink{classPipeStream_a49da5042ebb817bbc3744429832908fa}{Pipe\-Stream} (string cmd, string envs=\char`\"{}\char`\"{})  throw (\-Input\-Byte\-Stream\-Error)
\begin{DoxyCompactList}\small\item\em Creates a stream which returns the output of a given command. \end{DoxyCompactList}\item 
\hyperlink{classPipeStream_a4d17af15467f42d006f3283d4f84119a}{$\sim$\-Pipe\-Stream} ()
\item 
string \hyperlink{classPipeStream_a0997cbdd01678372dcbf358352099a38}{get\-Result} (bool all\-Of\-File=false, bool gobble\-Rest=true)  throw (\-Input\-Byte\-Stream\-Error)
\begin{DoxyCompactList}\small\item\em Returns the contents of the stream as a string. \end{DoxyCompactList}\item 
virtual void \hyperlink{classPipeStream_ab059872aafd84de6aa9541224742bb93}{close} (void)
\begin{DoxyCompactList}\small\item\em Closes the stream, and reaps the process status. \end{DoxyCompactList}\item 
int \hyperlink{classPipeStream_a36bab59c3f839d6ab1dfb189d419ccf2}{get\-Termination\-Status} (void)
\begin{DoxyCompactList}\small\item\em Returns the exit status of the command at the end of the pipe. \end{DoxyCompactList}\item 
pid\-\_\-t \hyperlink{classPipeStream_a9c0b9f5a256743330073af618d9fae8a}{get\-Pid} (void) const 
\begin{DoxyCompactList}\small\item\em Returns the P\-I\-D of the running process. \end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Additional Inherited Members}


\subsection{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 \hyperlink{classInputByteStream}{Input\-Byte\-Stream}, plus an additional one which retrieves the entire result as a string. 

\subsection{Constructor \& Destructor Documentation}
\hypertarget{classPipeStream_a49da5042ebb817bbc3744429832908fa}{\index{Pipe\-Stream@{Pipe\-Stream}!Pipe\-Stream@{Pipe\-Stream}}
\index{Pipe\-Stream@{Pipe\-Stream}!PipeStream@{Pipe\-Stream}}
\subsubsection[{Pipe\-Stream}]{\setlength{\rightskip}{0pt plus 5cm}Pipe\-Stream\-::\-Pipe\-Stream (
\begin{DoxyParamCaption}
\item[{string}]{cmd, }
\item[{string}]{envs = {\ttfamily \char`\"{}\char`\"{}}}
\end{DoxyParamCaption}
) throw  {\bf Input\-Byte\-Stream\-Error}) }}\label{classPipeStream_a49da5042ebb817bbc3744429832908fa}


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 {\ttfamily P\-A\-T\-H H\-O\-M\-E L\-O\-G\-N\-A\-M\-E S\-H\-E\-L\-L T\-M\-P\-D\-I\-R}, 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 {\ttfamily env1=val1 env2= env3}, then {\ttfamily env1} would receive the value {\ttfamily val1}, {\ttfamily env2} would receive a null value, and {\ttfamily env3} would be inherited.

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

If there's no way of doing this on a particular platform, throw {\ttfamily \hyperlink{classInputByteStreamError}{Input\-Byte\-Stream\-Error}} always.


\begin{DoxyParams}{Parameters}
{\em cmd} & the command to be run\\
\hline
{\em envs} & if specified, this is a list of environment variables; if it is an empty string, {\ttfamily \char`\"{}\char`\"{}} (the default), then a default list of variables is inherited\\
\hline
\end{DoxyParams}

\begin{DoxyExceptions}{Exceptions}
{\em \hyperlink{classInputByteStreamError}{Input\-Byte\-Stream\-Error}} & on any errors \\
\hline
\end{DoxyExceptions}


References Pipe\-Stream\-Signal\-Handling\-::expect\-Another(), normal, N\-U\-L\-L, Util\-::string\-\_\-list\-\_\-to\-\_\-array(), and Util\-::tokenise\-\_\-string().

\hypertarget{classPipeStream_a4d17af15467f42d006f3283d4f84119a}{\index{Pipe\-Stream@{Pipe\-Stream}!$\sim$\-Pipe\-Stream@{$\sim$\-Pipe\-Stream}}
\index{$\sim$\-Pipe\-Stream@{$\sim$\-Pipe\-Stream}!PipeStream@{Pipe\-Stream}}
\subsubsection[{$\sim$\-Pipe\-Stream}]{\setlength{\rightskip}{0pt plus 5cm}Pipe\-Stream\-::$\sim$\-Pipe\-Stream (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
)}}\label{classPipeStream_a4d17af15467f42d006f3283d4f84119a}


\subsection{Member Function Documentation}
\hypertarget{classPipeStream_ab059872aafd84de6aa9541224742bb93}{\index{Pipe\-Stream@{Pipe\-Stream}!close@{close}}
\index{close@{close}!PipeStream@{Pipe\-Stream}}
\subsubsection[{close}]{\setlength{\rightskip}{0pt plus 5cm}void Pipe\-Stream\-::close (
\begin{DoxyParamCaption}
\item[{void}]{}
\end{DoxyParamCaption}
)\hspace{0.3cm}{\ttfamily [virtual]}}}\label{classPipeStream_ab059872aafd84de6aa9541224742bb93}


Closes the stream, and reaps the process status. 

If the process has not already terminated, this method attempts to kill it, by sending first H\-U\-P then K\-I\-L\-L. 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 \hyperlink{classInputByteStream_a49494d95c8fb2c018330564ceeec6cc8}{Input\-Byte\-Stream}.



References Input\-Byte\-Stream\-::close(), Pipe\-Stream\-Signal\-Handling\-::got\-\_\-status(), and normal.

\hypertarget{classPipeStream_a9c0b9f5a256743330073af618d9fae8a}{\index{Pipe\-Stream@{Pipe\-Stream}!get\-Pid@{get\-Pid}}
\index{get\-Pid@{get\-Pid}!PipeStream@{Pipe\-Stream}}
\subsubsection[{get\-Pid}]{\setlength{\rightskip}{0pt plus 5cm}pid\-\_\-t Pipe\-Stream\-::get\-Pid (
\begin{DoxyParamCaption}
\item[{void}]{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}}\label{classPipeStream_a9c0b9f5a256743330073af618d9fae8a}


Returns the P\-I\-D of the running process. 

After the process has finished, this will return zero.

\begin{DoxyReturn}{Returns}
the process's P\-I\-D, or zero if it has finished 
\end{DoxyReturn}
\hypertarget{classPipeStream_a0997cbdd01678372dcbf358352099a38}{\index{Pipe\-Stream@{Pipe\-Stream}!get\-Result@{get\-Result}}
\index{get\-Result@{get\-Result}!PipeStream@{Pipe\-Stream}}
\subsubsection[{get\-Result}]{\setlength{\rightskip}{0pt plus 5cm}string Pipe\-Stream\-::get\-Result (
\begin{DoxyParamCaption}
\item[{bool}]{all\-Of\-File = {\ttfamily false}, }
\item[{bool}]{gobble\-Rest = {\ttfamily true}}
\end{DoxyParamCaption}
) throw  {\bf Input\-Byte\-Stream\-Error}) }}\label{classPipeStream_a0997cbdd01678372dcbf358352099a38}


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 {\ttfamily get\-Termination\-Status}.


\begin{DoxyParams}{Parameters}
{\em all\-Of\-File} & if true, then all of the file is read into the string; if false (the default), only the first line is returned, {\itshape not} including the newline or carriage-\/return which ends the line\\
\hline
{\em gobble\-Rest} & if true (the default) then gobble the rest of the file; has an effect only if {\ttfamily all\-Of\-File} was false\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the stream contents (or some of it, depending on the parameter values) as a string 
\end{DoxyReturn}

\begin{DoxyExceptions}{Exceptions}
{\em \hyperlink{classInputByteStreamError}{Input\-Byte\-Stream\-Error}} & if there is some problem reading the stream \\
\hline
\end{DoxyExceptions}


References normal, S\-S\-\_\-\-S\-T\-R\-I\-N\-G, and S\-S\-T\-R\-E\-A\-M.



Referenced by Pk\-Font\-::\-Pk\-Font().

\hypertarget{classPipeStream_a36bab59c3f839d6ab1dfb189d419ccf2}{\index{Pipe\-Stream@{Pipe\-Stream}!get\-Termination\-Status@{get\-Termination\-Status}}
\index{get\-Termination\-Status@{get\-Termination\-Status}!PipeStream@{Pipe\-Stream}}
\subsubsection[{get\-Termination\-Status}]{\setlength{\rightskip}{0pt plus 5cm}int Pipe\-Stream\-::get\-Termination\-Status (
\begin{DoxyParamCaption}
\item[{void}]{}
\end{DoxyParamCaption}
)}}\label{classPipeStream_a36bab59c3f839d6ab1dfb189d419ccf2}


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 \hyperlink{classPipeStream_ab059872aafd84de6aa9541224742bb93}{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 {\ttfamily 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.

\begin{DoxyReturn}{Returns}
the exit status of the process. 
\end{DoxyReturn}


Referenced by Pk\-Font\-::\-Pk\-Font().



The documentation for this class was generated from the following files\-:\begin{DoxyCompactItemize}
\item 
\hyperlink{PipeStream_8h}{Pipe\-Stream.\-h}\item 
\hyperlink{PipeStream_8cc}{Pipe\-Stream.\-cc}\end{DoxyCompactItemize}