READPIPESTRINGS(3A)                           READPIPESTRINGS(3A)



  NAME
       ReadPipeStrings, ReadPipeStringsV - asynchronously read a
       lines of data from a pipe as strings


  SYNOPSIS
       ReadPipeStrings (filter, ready, error, arg, cmd, arg ...)
       int (*filter)();
       int (*ready)();
       char *(*error)();
       int arg;
       char *cmd;
       char *arg;

       ReadPipeStringsV (filter, ready, error, arg, cmd, argv)
       int (*filter)();
       int (*ready)();
       char *(*error)();
       int arg;
       char *cmd;
       char *argv;

  DESCRIPTION
       ReadPipeStrings and ReadPipeStringsV read lines of data from
       a command and processes them as an array of strings.  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 ReadPipeStrings , arguments for the
       command (starting with arg as argument zero) follow the
       command in a NULL terminated parameter list.  For
       ReadPipeStringsV , the arguments are in the NULL-terminated
       array of strings argv.  The function filter is called for
       each line read, the function close is called after the pipe
       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 filter is as follows:


  Page 1                                           (printed 9/3/91)

  READPIPESTRINGS(3A)                           READPIPESTRINGS(3A)



            char *filter (arg, error, buf, length, strings,
            nstrings)
            int arg;
            int error;
            char *buf;
            int length;
            char **strings;
            int nstrings;

       The user-supplied argument to ReadPipeStrings or
       ReadPipeStringsV 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 current array of strings is pointed to by
       strings and the number of strings in it is in nstrings .
       There is a NULL pointer after the last element in the array.
       Because of buffer reallocation, the values in strings may
       change between calls to filter.

       The filter function returns a pointer to a new string to be
       stored in the array.  If the pointer is NULL, no new string
       is added and the line is effectively ignored.  The string
       returned may be the same address passed by the parameter
       buf, or it may be another string entirely.  The string may
       also be modified within the buffer provided, and the pointer
       returned may point within the buffer, so long as the no
       memory outside the space pointed to by the original value of
       buf for length bytes is modified.

       The calling sequence for ready is as follows:

            ready (arg, status, strings, nstrings, buf)
            int arg;
            int status;
            char **strings;
            int nstrings;
            char *buf;

       The first argument arg is the argument supplied to
       ReadFileData.  The array of strings is passed in strings and


  Page 2                                           (printed 9/3/91)

  READPIPESTRINGS(3A)                           READPIPESTRINGS(3A)



       the number of strings in it is passed in nstrings.  The
       buffer used to store strings as they are read in is returned
       in buf . The application is responsible for freeing strings,
       buf, and any other dynamically allocated buffer returned by
       filter 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 ReadPipeStrings or
       ReadPipeStringsV is passed in arg and an error code
       interpreted the same as the system global variable errno is
       passed in errno .

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









  Page 3                                           (printed 9/3/91)