READFILELINES(3A)                               READFILELINES(3A)



  NAME
       ReadFileLines - asynchronously read lines of data from a
       file


  SYNOPSIS
       int ReadFileLines (line, ready, error, arg, name)
       int (*line)();
       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 line 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 line is as follows:

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

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


  Page 1                                           (printed 9/3/91)

  READFILELINES(3A)                               READFILELINES(3A)



       next line, the address is passed to free(3).

       The calling sequence for ready is as follows:

            ready (arg)
            int arg;

       The argument arg is the argument supplied to ReadFileLines.

       The calling sequence for error is as follows:

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

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

       ReadFileLines 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.  ReadFileLines 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), WriteFileData(3A),
       WriteFileLines(3A), WritePipeData(3A), WritePipeLines(3A)









  Page 2                                           (printed 9/3/91)