src/pipethrough.3

   1 .\"     $NetBSD: mdoc.template,v 1.5 2002/01/12 02:24:29 wiz Exp $
   2 .\"
   3 .\" Copyright notice
   4 .\"
   5 .\" The uncommented requests are required for all man pages.
   6 .\" The commented requests should be uncommented and used where appropriate.
   7 .Dd September 24, 2004
   8 .Dt pipethrough 3
   9 .Os
  10 .Sh NAME
  11 .Nm pipethrough
  12 .Nd pipe a buffer through a child command and receive two
  13 buffers containing the stdout and stderr output of the child process.
  14 .Sh LIBRARY
  15 none -- must be included directly.
  16 .Sh SYNOPSIS
  17 .Bd -literal
  18 #include <pipethrough.h>
  19
  20 extern int pipethrough(const     char                  *command,
  21                        const     struct pipe_inbuffer  *stdin_buf,
  22                        /*@out@*/ struct pipe_outbuffer *stdout_buf,
  23                        /*@out@*/ struct pipe_outbuffer *stderr_buf,
  24                        /*@out@*/ int                   *status);
  25 .Ed
  26 .Sh DESCRIPTION
  27 The pipethrough function executes the \fIcommand\fR via the shell. The
  28 command's input is the data provided in \fIstdin_buf\fR. The output buffers
  29 \fIstdout_buf\fR and \fIstderr_buf\fR will be filled with the output of the
  30 command. After usage they must be freed using pipe_outbuffer_finalize(3).
  31 .Sh RETURN VALUES
  32 On success, pipethrough returns 0. On failure it returns -1 and sets
  33 \fIerrno\fR to the first error that occurred. Later errors are discarded
  34 silently.
  35 .Sh ENVIRONMENT
  36 .Bl -tag -width Fl
  37 .It SHELL
  38 The shell invoked by pipethrough. Defaults to /bin/sh.
  39 .El
  40 .Pp
  41 .Sh FILES
  42 .Bl -tag -width Fl
  43 .It /bin/sh
  44 The default shell.
  45 .El
  46 .Pp
  47 .Sh EXAMPLES
  48 TODO
  49 .Sh ERRORS
  50 The various errors that can occur during execution of close(2), dup2(2),
  51 read(2), write(2), execl(3).
  52 .\" .Sh SEE ALSO
  53 .\" Cross-references should be ordered by section (low to high), then in
  54 .\"     alphabetical order.
  55 .Sh STANDARDS
  56 pipethrough does not appear in any standard I know of.
  57 .\" .Sh HISTORY
  58 .Sh AUTHORS
  59 Roland Illig
  60 .Aq roland.illig@gmx.de .
  61 .Sh BUGS
  62 None known yet. If you find bugs, please report them to the authors.
  63 .Sh SECURITY CONSIDERATIONS
  64 The \fIcommand\fR must be a properly quoted shell command. That is,
  65 don't include file names without quoting them.