doc/pod/qio.pod

   1 =head1 NAME
   2
   3 qio - Quick I/O routines for reading files
   4
   5 =head1 SYNOPSIS
   6
   7 B<#include E<lt>inn/qio.hE<gt>>
   8
   9 B<QIOSTATE *QIOopen(const char *>I<name>B<);>
  10
  11 B<QIOSTATE *QIOfdopen(int> I<fd>B<);>
  12
  13 B<void QIOclose(QIOSTATE *>I<qp>B<);>
  14
  15 B<char *QIOread(QIOSTATE *>I<qp>B<);>
  16
  17 B<int QIOfileno(QIOSTATE *>I<qp>B<);>
  18
  19 B<size_t QIOlength(QIOSTATE *>I<qp>B<);>
  20
  21 B<int QIOrewind(QIOSTATE *>I<qp>B<);>
  22
  23 B<off_t QIOtell(QIOSTATE *>I<qp>B<);>
  24
  25 B<bool QIOerror(QIOSTATE *>I<qp>B<);>
  26
  27 B<bool QIOtoolong(QIOSTATE *>I<qp>B<);>
  28
  29 =head1 DESCRIPTION
  30
  31 The routines described in this manual page are part of libinn(3).  They
  32 are used to provide quick read access to files; the QIO routines use
  33 buffering adapted to the block size of the device, similar to stdio, but
  34 with a more convenient syntax for reading newline-terminated lines.  QIO
  35 is short for "Quick I/O" (a bit of a misnomer, as QIO provides read-only
  36 access to files only).
  37
  38 The QIOSTATE structure returned by B<QIOopen> and B<QIOfdopen> is the
  39 analog to stdio's FILE structure and should be treated as a black box by
  40 all users of these routines.  Only the above API should be used.
  41
  42 B<QIOopen> opens the given file for reading.  For regular files, if your
  43 system provides that information and the size is reasonable, QIO will use
  44 the block size of the underlying file system as its buffer size;
  45 otherwise, it will default to a buffer of 8 KB.  Returns a pointer to use
  46 for subsequent calls, or NULL on error.  B<QIOfdopen> performs the same
  47 operation except on an already-open file descriptor (I<fd> must designate
  48 a file open for reading).
  49
  50 B<QIOclose> closes the open file and releases any resources used by the
  51 QIOSTATE structure.  The QIOSTATE pointer should not be used again after
  52 it has been passed to this function.
  53
  54 B<QIOread> reads the next newline-terminated line in the file and returns
  55 a pointer to it, with the trailing newline replaced by nul.  The returned
  56 pointer is a pointer into a buffer in the QIOSTATE object and therefore
  57 will remain valid until B<QIOclose> is called on that object.  If EOF is
  58 reached, an error occurs, or if the line is longer than the buffer size,
  59 NULL is returned instead.  To distinguish between the error cases, use
  60 B<QIOerror> and B<QIOtoolong>.
  61
  62 B<QIOfileno> returns the descriptor of the open file.
  63
  64 B<QIOlength> returns the length in bytes of the last line returned by
  65 B<QIOread>.  Its return value is only defined after a successful call to
  66 B<QIOread>.
  67
  68 B<QIOrewind> sets the read pointer back to the beginning of the file and
  69 reads the first block of the file in anticipation of future reads.  It
  70 returns 0 if successful and -1 on error.
  71
  72 B<QIOtell> returns the current value of the read pointer (the lseek(2)
  73 offset at which the next line will start).
  74
  75 B<QIOerror> returns true if there was an error in the last call to
  76 B<QIOread>, false otherwise.  B<QIOtoolong> returns true if there was an
  77 error and the error was that the line was too long.  If B<QIOread> returns
  78 NULL, these functions should be called to determine what happened.  If
  79 B<QIOread> returned NULL and B<QIOerror> is false, EOF was reached.  Note
  80 that if B<QIOtoolong> returns true, the next call to B<QIOread> will try
  81 to read the remainder of the line and will likely return a partial line;
  82 users of this library should in general treat long lines as fatal errors.
  83
  84 =head1 EXAMPLES
  85
  86 This block of code opens F</etc/motd> and reads it a line at a time,
  87 printing out each line preceeded by its offset in the file.
  88
  89     QIOSTATE *qp;
  90     off_t offset;
  91     char *p;
  92
  93     qp = QIOopen("/etc/motd");
  94     if (qp == NULL) {
  95         perror("Open error");
  96         exit(1);
  97     }
  98     for (p = QIOread(qp); p != NULL; p = QIOread(qp))
  99         printf("%ld: %s\n", (unsigned long) QIOtell(qp), p);
 100     if (QIOerror(qp)) {
 101         perror("Read error");
 102         exit(1);
 103     }
 104     QIOclose(qp);
 105
 106 =head1 HISTORY
 107
 108 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Updated by
 109 Russ Allbery <rra@stanford.edu>.
 110
 111 $Id: qio.pod 5909 2002-12-03 05:17:18Z vinocur $