READPIPELINES(3A)                               READPIPELINES(3A)



  NAME
       ReadPipeLines, ReadPipeLinesV - asynchronously read lines of
       data from a pipe


  SYNOPSIS
       ReadPipeLines (line, ready, error, arg, cmd, arg ...)
       int (*line)();
       int (*ready)();
       char *(*error)();
       int arg;
       char *cmd;
       char *arg;

       ReadPipeLinesV (line, ready, error, arg, cmd, argv)
       int (*line)();
       int (*ready)();
       char *(*error)();
       int arg;
       char *cmd;
       char *argv;

  DESCRIPTION
       ReadPipeLines and ReadPipeLinesV read lines of data from a
       command.  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 ReadPipeLines , arguments
       for the command (starting with arg as argument zero) follow
       the command in a NULL terminated parameter list.  For
       ReadPipeLinesV , the arguments are in the NULL-terminated
       array of strings argv.  The function line is called for each
       line read, the function ready is called after the file has
       been closed, and the function error is called upon an error.
       Any 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 line is as follows:



  Page 1                                           (printed 9/3/91)

  READPIPELINES(3A)                               READPIPELINES(3A)



            char *line (arg, error, buf, length)
            int arg;
            int error;
            char *buf;
            int length;

       The user-supplied argument to ReadPipeLines or
       ReadPipeLinesV is in arg.  The error code, error, is always
       zero.  The line and its length are in buf and length.  The
       length includes the terminating newline, but not the zero
       byte.  The line function returns a buffer for the next line
       or NULL.  The buffer may be the same address passed by the
       parameter buf, or it may be another malloced area of at
       least BUFSIZ bytes.  The buffer must be in dynamically
       allocated space, since if there is no next line, the address
       is passed to free(3).

       The calling sequence for ready is as follows:

            ready (arg, status)
            int arg;
            int status;

       The first argument arg is the argument supplied to
       ReadPipeLines or ReadPipeLinesV.  The child's exit status is
       in status.

       The calling sequence for error is as follows:

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

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

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



  Page 2                                           (printed 9/3/91)

  READPIPELINES(3A)                               READPIPELINES(3A)



  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.
       ReadPipeLines and ReadPipeLinesV 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),
       ReadPipeData(3A), ReadPipeStrings(3A), WriteFileData(3A),
       WriteFileLines(3A), WritePipeData(3A), WritePipeLines(3A)





























  Page 3                                           (printed 9/3/91)