Index for Section 3

Alphabetical listing for Q

Bottom of page

qio(3)
NAME
  qio - Quick I/O routines for reading files

SYNOPSIS
  #include <inn/qio.h>

  QIOSTATE *QIOopen(const char *name);

  QIOSTATE *QIOfdopen(int fd);

  void QIOclose(QIOSTATE *qp);

  char *QIOread(QIOSTATE *qp);

  int QIOfileno(QIOSTATE *qp);

  size_t QIOlength(QIOSTATE *qp);

  int QIOrewind(QIOSTATE *qp);

  off_t QIOtell(QIOSTATE *qp);

  bool QIOerror(QIOSTATE *qp);

  bool QIOtoolong(QIOSTATE *qp);

DESCRIPTION
  The routines described in this manual page are part of libinn(3).  They are
  used to provide quick read access to files; the QIO routines use buffering
  adapted to the block size of the device, similar to stdio, but with a more
  convenient syntax for reading newline-terminated lines.  QIO is short for
  "Quick I/O" (a bit of a misnomer, as QIO provides read-only access to files
  only).

  The QIOSTATE structure returned by QIOopen and QIOfdopen is the analog to
  stdio's FILE structure and should be treated as a black box by all users of
  these routines.  Only the above API should be used.

  QIOopen opens the given file for reading.  For regular files, if your
  system provides that information and the size is reasonable, QIO will use
  the block size of the underlying file system as its buffer size; otherwise,
  it will default to a buffer of 8 KB.	Returns a pointer to use for
  subsequent calls, or NULL on error.  QIOfdopen performs the same operation
  except on an already-open file descriptor (fd must designate a file open
  for reading).

  QIOclose closes the open file and releases any resources used by the
  QIOSTATE structure.  The QIOSTATE pointer should not be used again after it
  has been passed to this function.

  QIOread reads the next newline-terminated line in the file and returns a
  pointer to it, with the trailing newline replaced by nul.  The returned
  pointer is a pointer into a buffer in the QIOSTATE object and therefore
  will remain valid until QIOclose is called on that object.  If EOF is
  reached, an error occurs, or if the line is longer than the buffer size,
  NULL is returned instead.  To distinguish between the error cases, use
  QIOerror and QIOtoolong.

  QIOfileno returns the descriptor of the open file.

  QIOlength returns the length in bytes of the last line returned by QIOread.
  Its return value is only defined after a successful call to QIOread.

  QIOrewind sets the read pointer back to the beginning of the file and reads
  the first block of the file in anticipation of future reads.	It returns 0
  if successful and -1 on error.

  QIOtell returns the current value of the read pointer (the lseek(2) offset
  at which the next line will start).

  QIOerror returns true if there was an error in the last call to QIOread,
  false otherwise.  QIOtoolong returns true if there was an error and the
  error was that the line was too long.	 If QIOread returns NULL, these
  functions should be called to determine what happened.  If QIOread returned
  NULL and QIOerror is false, EOF was reached.	Note that if QIOtoolong
  returns true, the next call to QIOread will try to read the remainder of
  the line and will likely return a partial line; users of this library
  should in general treat long lines as fatal errors.

EXAMPLES
  This block of code opens /etc/motd and reads it a line at a time, printing
  out each line preceeded by its offset in the file.

      QIOSTATE *qp;
      off_t offset;
      char *p;

      qp = QIOopen("/etc/motd");
      if (qp == NULL) {
	  perror("Open error");
	  exit(1);
      }
      for (p = QIOread(qp); p != NULL; p = QIOread(qp))
	  printf("%ld: %s\n", (unsigned long) QIOtell(qp), p);
      if (QIOerror(qp)) {
	  perror("Read error");
	  exit(1);
      }
      QIOclose(qp);

HISTORY
  Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Updated by
  Russ Allbery <rra@stanford.edu>.

  $Id: qio.3 5912 2002-12-03 05:31:11Z vinocur $

Index for Section 3

Alphabetical listing for Q

Top of page