READFILESTRINGS(3A)                           READFILESTRINGS(3A)



  NAME
       ReadFileStrings - asynchronously read a lines of data from a
       file as strings


  SYNOPSIS
       int ReadFileStrings (filter, ready, error, arg, name)
       int (*filter)();
       int (*ready)();
       char *(*error)();
       int arg;
       char *name;

  DESCRIPTION
       ReadFileLines reads a file for lines of data.  The name of
       the file to read is in name.  The function filter is called
       for each line read in the file.  The function ready is
       called when the data has been read, 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
       file 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:

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

       The user-supplied argument to ReadFileStrings 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


  Page 1                                           (printed 9/3/91)

  READFILESTRINGS(3A)                           READFILESTRINGS(3A)



       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, strings, nstrings, buf)
            int arg;
            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
       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 ReadFileData is passed in arg and
       an error code interpreted the same as the system global
       variable errno is passed in errno .



  Page 2                                           (printed 9/3/91)

  READFILESTRINGS(3A)                           READFILESTRINGS(3A)



       ReadFileData returns -1 if there was an error setting up the
       I/O procedure, or zero on success.

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

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



























  Page 3                                           (printed 9/3/91)