.\"	$NetBSD: mdoc.template,v 1.5 2002/01/12 02:24:29 wiz Exp $
.\"
.\" Copyright notice
.\"
.\" The uncommented requests are required for all man pages.
.\" The commented requests should be uncommented and used where appropriate.
.Dd September 24, 2004
.Dt pipethrough 3
.Os
.Sh NAME
.Nm pipethrough
.Nd pipe a buffer through a child command and receive two
buffers containing the stdout and stderr output of the child process.
.Sh LIBRARY
none -- must be included directly.
.Sh SYNOPSIS
.Bd -literal
#include <pipethrough.h>

extern int pipethrough(const     char                  *command,
                       const     struct pipe_inbuffer  *stdin_buf,
                       /*@out@*/ struct pipe_outbuffer *stdout_buf,
                       /*@out@*/ struct pipe_outbuffer *stderr_buf,
                       /*@out@*/ int                   *status);
.Ed
.Sh DESCRIPTION
The pipethrough function executes the \fIcommand\fR via the shell. The
command's input is the data provided in \fIstdin_buf\fR. The output buffers
\fIstdout_buf\fR and \fIstderr_buf\fR will be filled with the output of the
command. After usage they must be freed using pipe_outbuffer_finalize(3).
.Sh RETURN VALUES
On success, pipethrough returns 0. On failure it returns -1 and sets
\fIerrno\fR to the first error that occurred. Later errors are discarded
silently.
.Sh ENVIRONMENT
.Bl -tag -width Fl
.It SHELL
The shell invoked by pipethrough. Defaults to /bin/sh.
.El
.Pp
.Sh FILES
.Bl -tag -width Fl
.It /bin/sh
The default shell.
.El
.Pp
.Sh EXAMPLES
TODO
.Sh ERRORS
The various errors that can occur during execution of close(2), dup2(2),
read(2), write(2), execl(3).
.\" .Sh SEE ALSO
.\" Cross-references should be ordered by section (low to high), then in
.\"     alphabetical order.
.Sh STANDARDS
pipethrough does not appear in any standard I know of.
.\" .Sh HISTORY
.Sh AUTHORS
Roland Illig
.Aq roland.illig@gmx.de .
.Sh BUGS
None known yet. If you find bugs, please report them to the authors.
.Sh SECURITY CONSIDERATIONS
The \fIcommand\fR must be a properly quoted shell command. That is,
don't include file names without quoting them.