READPIPEDATA(3A)                                 READPIPEDATA(3A)



  NAME
       ReadPipeData, ReadPipeDataV - asynchronously read a block of
       data from a pipe


  SYNOPSIS
       ReadPipeData (ready, error, arg, size, cmd, arg ...)
       int (*ready)();
       char *(*error)();
       int arg;
       int size;
       char *cmd;
       char *arg;

       ReadPipeDataV (ready, error, arg, size, cmd, argv)
       int (*ready)();
       char *(*error)();
       int arg;
       int size;
       char *cmd;
       char *argv;

  DESCRIPTION
       ReadPipeData and ReadPipeDataV read a pipe for binary data.
       A command is executed with its standard output and error
       files redirected to a pipe.  The full path name of the
       command to execute is in cmd.  For ReadPipeData , arguments
       for the command (starting with arg as argument zero) follow
       the command in a NULL terminated parameter list.  For
       ReadPipeDataV , the arguments are in the NULL-terminated
       array of strings argv.  The number of bytes to read is in
       size.  If size is zero, all output from the pipe is read.
       The function ready is called when the data has been read,
       and the function error is called upon an error.  Either
       function may be NULL, in which case it will not be called.
       When there is an error, the pipe is closed, so exactly one
       of the two functions ready and error is called.  The
       argument arg is passed to both routines.

       The calling sequence for ready is as follows:


  Page 1                                           (printed 9/3/91)

  READPIPEDATA(3A)                                 READPIPEDATA(3A)



            ready (arg, status, buf, length)
            int arg;
            int status;
            char *buf;
            int length;

       The first argument arg is the argument supplied to
       ReadPipeData or ReadPipeDataV.  The child's exit status is
       in status, buf is the data in allocated memory, and length
       is the number of bytes read.  The application is responsible
       for freeing the buffer when done with it using the library
       routine free (3).

       The calling sequence for error is as follows:

            error (arg, errno)
            int arg;
            int errno;

       The user-supplied data to ReadPipeData or ReadPipeDataV is
       passed in arg and an error code interpreted the same as the
       system global variable errno is passed in errno .

       ReadPipeData and ReadPipeDataV return the process ID of the
       child process on success, or -1 upon error.

  NOTES
       There are lower-level asynchronous I/O routines AddIoProc,
       RemoveIoProc, OpenReadPipe, and ClosePipe that provide
       greater flexibility at the expense of greater coding effort.
       ReadPipeData and ReadPipeDataV use these routines to set up
       an asynchronous read procedure.

  SEE ALSO
       XtAppAddInput(3Xt), XtRemoveInput(3Xt), AddIoProc(3A),
       RemoveIoProc(3A), OpenReadPipe(3A), ClosePipe(3A),
       ReadFileData(3A), ReadFileLines(3A), ReadFileStrings(3A),
       ReadPipeLines(3A), ReadPipeStrings(3A), WriteFileData(3A),
       WriteFileLines(3A), WritePipeData(3A), WritePipeLines(3A)



  Page 2                                           (printed 9/3/91)